Introduction
If users cannot see the Unity Catalog Metastore in Databricks, they might experience issues like:
- No catalogs, schemas, or tables visible in Unity Catalog UI.
SHOW CATALOGS;
returns an empty list.- Access denied when trying to use Unity Catalog.
- Users cannot see Unity Catalog but administrators can.
๐จ Possible causes:
- The Metastore is not properly assigned to the workspace.
- The user lacks permissions to access Unity Catalog.
- Clusters and SQL Warehouses are not configured for Unity Catalog.
- The workspace is using Hive Metastore instead of Unity Catalog.
This guide walks through step-by-step solutions to resolve these issues.
Step 1: Verify If Unity Catalog Metastore Is Assigned to the Workspace
Symptoms:
- Users cannot see any catalogs in Unity Catalog.
- Error: “No metastore configured for this workspace.”
Causes:
- Unity Catalog Metastore has not been assigned to the workspace.
- Wrong workspace ID was used when assigning the metastore.
Fix:
โ Check if the workspace has a Unity Catalog Metastore assigned:
SHOW METASTORES;
โ If no metastore is assigned, list available metastores:
databricks unity-catalog metastores list
โ Assign the metastore to your Databricks workspace:
databricks unity-catalog metastores assign --metastore-id <metastore-id> --workspace-id <workspace-id>
โ Confirm the assignment with:
SHOW METASTORES;
Step 2: Ensure the User Has Permission to View the Unity Catalog Metastore
Symptoms:
- Admins can see Unity Catalog, but users cannot.
- Error: “PERMISSION_DENIED: Cannot access Unity Catalog.”
Causes:
- The user lacks privileges to access the Unity Catalog Metastore.
- Unity Catalog permissions were not properly configured.
Fix:
โ Check Unity Catalog permissions for the user:
SHOW GRANTS ON METASTORE;
โ Grant Unity Catalog access to users or groups:
GRANT USE CATALOG ON METASTORE TO `user@example.com`;
GRANT CREATE CATALOG ON METASTORE TO `user@example.com`;
โ If using groups, assign permissions at the group level:
GRANT USE CATALOG ON METASTORE TO `engineering_team`;
โ Verify user permissions after granting access:
SHOW GRANTS ON METASTORE;
Step 3: Check If the User Can See Catalogs and Schemas
Symptoms:
- Users cannot see catalogs, schemas, or tables inside Unity Catalog.
- Running
SHOW CATALOGS;
returns an empty list.
Causes:
- The user lacks permissions to view catalogs inside Unity Catalog.
- No catalogs or schemas have been created yet.
Fix:
โ Check available catalogs:
SHOW CATALOGS;
โ Grant catalog access to users or groups:
GRANT USE CATALOG ON CATALOG my_catalog TO `user@example.com`;
GRANT CREATE SCHEMA ON CATALOG my_catalog TO `user@example.com`;
โ Check available schemas in a catalog:
SHOW SCHEMAS IN my_catalog;
โ Ensure the user can see tables:
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO `user@example.com`;
โ Confirm permissions by running:
SHOW GRANTS ON CATALOG my_catalog;
Step 4: Ensure Clusters and SQL Warehouses Support Unity Catalog
Symptoms:
- Users cannot see Unity Catalog when connected to a cluster.
- Error: “USE CATALOG command not recognized.”
- SQL queries fail when referencing Unity Catalog tables.
Causes:
- The Databricks cluster is not enabled for Unity Catalog.
- The SQL Warehouse does not support Unity Catalog.
Fix:
โ Ensure the cluster is Unity Catalog-enabled:
- Go to Databricks UI โ Clusters
- Edit the cluster โ Advanced options โ Enable Unity Catalog
- Restart the cluster after enabling Unity Catalog.
โ If using SQL Warehouses, ensure Unity Catalog is enabled:
- Go to Databricks UI โ SQL Warehouses
- Edit the warehouse settings to support Unity Catalog.
โ Test if Unity Catalog is accessible from the cluster:
SHOW CATALOGS;
Step 5: Check If Unity Catalog Is Enabled for the Workspace
Symptoms:
- Unity Catalog is missing from the Databricks UI.
- Users and admins cannot see Unity Catalog.
Causes:
- The workspace is using Hive Metastore instead of Unity Catalog.
- Unity Catalog is not enabled for this Databricks workspace.
Fix:
โ Check if Unity Catalog is enabled for the workspace:
databricks workspace get-status
โ If Unity Catalog is not enabled, contact Databricks Support or your Cloud Admin.
Step 6: Ensure AWS IAM or Azure AD Permissions Are Set Correctly
Symptoms:
- Unity Catalog is available, but users get permission errors when accessing data.
- AWS S3 / Azure ADLS storage permissions issues.
Causes:
- AWS IAM roles or Azure AD permissions are missing for Unity Catalog users.
- Storage access is blocked due to incorrect policy settings.
Fix:
โ For AWS IAM Role Permissions, ensure Unity Catalog has access to Glue and S3:
{
"Effect": "Allow",
"Action": ["glue:Get*", "glue:Create*", "s3:GetObject", "s3:PutObject"],
"Resource": "*"
}
โ Update IAM policy:
aws iam put-role-policy --role-name <your-role-name> --policy-name UnityCatalogAccess --policy-document file://policy.json
โ For Azure Storage and Key Vault, ensure proper access permissions:
az role assignment create --assignee <service-principal> --role "Storage Blob Data Contributor" --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<storage-name>
Step 7: Restart Databricks Clusters & SQL Warehouses
Symptoms:
- Permissions were granted, but users still cannot see Unity Catalog.
- Tables and schemas appear missing after updates.
Fix:
โ
Restart the affected Databricks clusters and SQL Warehouses.
โ
Ensure users re-login to Databricks to refresh permissions.
Final Troubleshooting Checklist
โ Step 1: Verify Unity Catalog Metastore Assignment
SHOW METASTORES;
- If no metastore is assigned, create and attach one.
โ Step 2: Grant Unity Catalog Access to Users
GRANT USE CATALOG ON METASTORE TO `user@example.com`;
- Ensure users have the right permissions to see Unity Catalog.
โ Step 3: Check Catalog & Schema Access
SHOW CATALOGS;
GRANT USE CATALOG ON CATALOG my_catalog TO `user@example.com`;
โ Step 4: Ensure Clusters & Warehouses Support Unity Catalog
- Restart clusters with Unity Catalog support enabled.
โ Step 5: Validate IAM and Storage Permissions (AWS / Azure)
- Ensure S3 / ADLS storage permissions allow access to Unity Catalog.
Conclusion
If users cannot see Unity Catalog Metastore in Databricks, ensure:
โ
A metastore is assigned to the workspace.
โ
Users have the right permissions for Unity Catalog.
โ
Clusters and SQL Warehouses support Unity Catalog.
โ
AWS IAM / Azure AD permissions are correctly set up.
By following this guide, you can resolve access issues and ensure users can view and manage data in Unity Catalog.