Introduction

The PERM001 – Access denied (user lacks permission) error occurs in Databricks Unity Catalog when a user attempts to access catalogs, schemas, or tables without the required permissions. This error is commonly related to insufficient privileges or misconfigured access control lists (ACLs) in Unity Catalog.

🚨 Common scenarios for the PERM001 error:

• Accessing a catalog, schema, or table without the correct permissions.
• Running SQL commands like USE CATALOG, SHOW TABLES, or SELECT without required grants.
• Writing or modifying data in a table without proper permissions.

Causes of PERM001 Error

1. Lack of Permissions on Catalog, Schema, or Table
   • Users may not have USE CATALOG or SELECT privileges.
   • Admins may not have granted permissions for the specific catalog, schema, or table.
2. Misconfigured Unity Catalog Permissions
   • The default roles in Unity Catalog may not include required permissions.
3. Cross-Workspace Access Issues
   • Unity Catalog does not automatically propagate permissions across workspaces.
4. Using a Legacy Cluster
   • Unity Catalog only works with Unity Catalog-enabled clusters, not legacy ones.
5. Service Principal or Role Missing Permissions
   • For jobs or service principals, permissions may not be correctly assigned in Unity Catalog.

Solutions and Fixes

1. Grant Necessary Permissions to the User

✅ Grant USE CATALOG and SELECT privileges:

GRANT USE CATALOG ON CATALOG my_catalog TO `user@example.com`;
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO `user@example.com`;

✅ Grant Permissions at the Schema Level (if needed):

GRANT USAGE ON SCHEMA my_catalog.my_schema TO `user@example.com`;
GRANT SELECT ON ALL TABLES IN SCHEMA my_catalog.my_schema TO `user@example.com`;

✅ Check User Permissions:

SHOW GRANTS ON TABLE my_catalog.my_schema.my_table;

2. Ensure Proper Roles and Groups Are Assigned

Unity Catalog uses role-based access control (RBAC). Ensure that the user is part of a group with appropriate permissions:

CREATE GROUP data_team;
GRANT USE CATALOG ON CATALOG my_catalog TO data_team;
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO data_team;

✅ Add the user to the group:

databricks groups add-member --group-name data_team --member-type user --member-name user@example.com

3. Verify Cluster Supports Unity Catalog

Unity Catalog requires Unity Catalog-enabled clusters. Ensure that:

• Go to Databricks UI → Clusters → Advanced Options → Unity Catalog Support is enabled.
• If necessary, create a new cluster with Unity Catalog support.
• Restart the cluster to apply the changes.

4. Check and Update Service Principal Permissions (for Jobs)

For Databricks jobs using Unity Catalog, ensure that the service principal or job role has the necessary permissions:

✅ Grant permissions to the service principal:

GRANT USE CATALOG ON CATALOG my_catalog TO `service-principal-name`;
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO `service-principal-name`;

5. Use Databricks Admin to Verify Permissions

✅ List all grants on a catalog or schema:

SHOW GRANTS ON CATALOG my_catalog;
SHOW GRANTS ON SCHEMA my_catalog.my_schema;

✅ Revoke and Re-grant Permissions (if required):

REVOKE ALL PRIVILEGES ON TABLE my_catalog.my_schema.my_table FROM `user@example.com`;
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO `user@example.com`;

Best Practices for Avoiding PERM001 Errors

1. Use Role-Based Access Control (RBAC): Assign roles to groups and manage permissions at the group level.
2. Audit and Monitor Permissions: Regularly audit permissions using SHOW GRANTS to prevent unauthorized access.
3. Use Unity Catalog-Enabled Clusters: Ensure all workloads use clusters that support Unity Catalog.
4. Grant Permissions at the Schema Level: Minimize table-specific grants by granting at the schema level.

Conclusion

The PERM001 – Access denied error in Databricks Unity Catalog is usually related to missing permissions or cluster misconfigurations. By granting the necessary privileges, enabling Unity Catalog support on clusters, and managing permissions at the group level, you can resolve this error and ensure secure, seamless access to data.