Introduction

Error Code: PERM002 indicates that Databricks has denied access to the workspace due to permission issues. This typically happens when:

• You lack required permissions to access the Databricks workspace.
• The workspace administrator has restricted access.
• Role or group assignments do not grant the necessary permissions.

Common Causes and Fixes for PERM002 Error

1. User Does Not Have Workspace Access

Symptoms:

• Error: “PERM002 – Workspace access denied.”
• Cannot log in to the Databricks workspace.

Causes:

• Your Databricks user account is not assigned to the workspace.
• Admin privileges are required, and your role lacks access permissions.

Fix:
✅ Verify if your account has access to the workspace:

• Contact your Databricks admin to confirm that your account is added to the workspace.

✅ Check workspace permissions using Databricks CLI (Admin Required):

databricks workspace list-permissions --path /

✅ Add the user to the workspace with appropriate permissions:

databricks permissions add --path / --principal <user-email> --permission CAN_MANAGE

2. Insufficient Permissions on Unity Catalog or Metastore

Symptoms:

• Error: “Workspace access denied” when accessing Unity Catalog.
• Cannot execute SQL queries or view Unity Catalog resources.

Causes:

• The user lacks permissions on Unity Catalog objects (catalogs, schemas, tables).
• The metastore is not assigned to your workspace.

Fix:
✅ Grant Unity Catalog permissions:

GRANT USE CATALOG ON CATALOG my_catalog TO `user@example.com`;

✅ Verify metastore assignment:

SHOW METASTORES;

If no metastore is assigned, follow these steps to assign one:

databricks unity-catalog metastores assign --metastore-id <metastore-id> --workspace-id <workspace-id>

3. Missing Admin Role or Privileges

Symptoms:

• Cannot manage clusters, jobs, or Unity Catalog settings.
• Error: “Workspace access denied.”

Causes:

• Your role does not have admin privileges on the workspace.
• Group-based access control restricts your ability to manage the workspace.

Fix:
✅ Check if you are an admin:

databricks admin list

✅ Assign admin privileges:

databricks admin add --user <user-email>

4. Azure Active Directory (AAD) or AWS IAM Misconfiguration

Symptoms:

• Cannot access Databricks despite having valid credentials.
• Error: “Access denied” when using Azure Databricks.

Causes:

• Azure Active Directory (AAD) roles are not assigned to your user account.
• AWS IAM roles lack permissions to access the workspace.

Fix for Azure Databricks:
✅ Verify AAD group membership:

az ad user show --id <user-email>

✅ Assign Azure AD roles to the user:

az role assignment create --assignee <user-email> --role "Contributor"

Fix for AWS Databricks:
✅ Ensure your IAM role has required permissions:

{
  "Effect": "Allow",
  "Action": [
    "databricks:ListClusters",
    "databricks:CreateCluster",
    "databricks:ReadWorkspaceItems"
  ],
  "Resource": "*"
}

Step-by-Step Troubleshooting Guide

1. Check User Permissions: databricks permissions list --path /
2. Verify Metastore and Unity Catalog Assignments: SHOW METASTORES;
3. Ensure Proper Role Assignment:
   • Azure: Check AAD role assignments.
   • AWS: Check IAM policies for required permissions.
4. Contact Workspace Admin:
   If none of the above works, contact your Databricks admin to confirm that your user account has access.

Best Practices to Prevent PERM002 Errors

✅ Use Group-Based Access Control

• Assign permissions at the group level rather than individual users.

✅ Regularly Audit Permissions

• Run periodic checks to ensure users have the appropriate access.

✅ Grant the Minimum Required Privileges

• Follow the principle of least privilege to minimize security risks.

✅ Document and Monitor Role Assignments

• Maintain a record of role and permission changes.

Conclusion

The PERM002 – Workspace Access Denied error usually indicates a permissions issue or role misconfiguration. By verifying workspace permissions, metastore assignments, and IAM roles, you can resolve access issues and ensure secure, appropriate access to your Databricks workspace. If you continue to face issues, contact your workspace admin or cloud provider support.