Introduction
Sharing tables with external users via Unity Catalog in Databricks allows secure cross-organization data access. However, external users may encounter access issues due to missing permissions, incorrect sharing configurations, or network restrictions.
🚨 Common issues faced by external users when accessing shared tables:
- Tables or catalogs are not visible to external users.
- Permission denied errors when querying shared tables.
- External users cannot authenticate or connect to shared data.
- Data is shared but cannot be accessed outside the original workspace.
This guide explores troubleshooting steps and best practices to ensure seamless data sharing for external users in Unity Catalog.
1. Verify That Unity Catalog Is Enabled for External Sharing
Symptoms:
- External users cannot see shared tables.
- Data provider has shared the table, but the recipient workspace does not show it.
Causes:
- Unity Catalog must be enabled for data sharing.
- The workspace must support Delta Sharing (Unity Catalog).
- The provider must explicitly grant access to external users.
Fix:
✅ Check if Unity Catalog is enabled in the workspace:
SHOW CATALOGS;
- If no catalogs appear, Unity Catalog may not be enabled.
✅ Ensure your Databricks workspace is configured for sharing:
- Go to Admin Console → Unity Catalog → Settings
- Check if data sharing is enabled for your account.
✅ Verify that external sharing is allowed in your workspace:
databricks unity-catalog metastores list
- Ensure the metastore is assigned to the correct workspace.
✅ Ensure the table is shared properly using Delta Sharing:
GRANT SELECT ON TABLE my_table TO SHARE my_share;
2. Confirm That External Users Have Been Added to the Share
Symptoms:
- External users do not see the shared table in their Databricks account.
- Permission errors when trying to access the table.
Causes:
- The table has been shared, but the external user is not listed as a recipient.
- Sharing settings do not allow access to external workspaces.
Fix:
✅ Check existing shares:
SHOW SHARES;
✅ List the recipients for a share:
SHOW RECIPIENTS IN SHARE my_share;
✅ Add the external user to the share:
GRANT USAGE ON SHARE my_share TO `external-user@example.com`;
✅ Confirm that the user’s workspace can accept the share:
- External users must accept the shared table in their workspace before using it.
3. Check Permissions for Shared Tables
Symptoms:
- Error: “Permission denied: User does not have SELECT privilege.”
- External users can see the table but cannot query it.
Causes:
- The external user has been added to the share but lacks SELECT permissions.
- The catalog or schema does not grant access to the user.
Fix:
✅ Ensure the external user has the correct permissions:
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO SHARE my_share;
✅ Check existing permissions:
SHOW GRANTS ON TABLE my_catalog.my_schema.my_table;
✅ Ensure the external user has usage permissions on the schema and catalog:
GRANT USAGE ON CATALOG my_catalog TO SHARE my_share;
GRANT USAGE ON SCHEMA my_catalog.my_schema TO SHARE my_share;
4. Ensure the External Workspace Has Enabled Delta Sharing
Symptoms:
- External users cannot list shared catalogs or tables.
- Error: “No shared catalogs found.”
Causes:
- The external Databricks workspace is not configured for Delta Sharing.
- The external workspace must explicitly enable Unity Catalog to accept shares.
Fix:
✅ Check if the recipient has accepted the share:
databricks unity-catalog shares list
✅ Ensure the recipient workspace has a Unity Catalog metastore configured.
- If the recipient does not have Unity Catalog enabled, they cannot access shared data.
✅ Recipient must explicitly accept the shared data in their account:
- Go to Databricks UI → Data → Shared Data
- Click “Accept Share”
5. Validate Network and Authentication Configuration
Symptoms:
- External users cannot authenticate to access shared tables.
- Error: “Could not establish a secure connection.”
Causes:
- Network restrictions block access to shared data.
- External users do not have the correct Databricks authentication setup.
Fix:
✅ Ensure external users authenticate using the correct method:
databricks configure --token
✅ If sharing data with AWS, ensure AWS PrivateLink is set up for cross-account access.
✅ For Azure Databricks, check that Azure AD is properly configured to accept external users.
✅ Check firewall and VPN settings to allow secure data access.
6. Check for Limitations With Cross-Cloud Data Sharing
Symptoms:
- External users are in AWS, but data is shared from Azure Databricks (or vice versa).
- Cross-region and cross-cloud sharing issues.
Causes:
- Unity Catalog Delta Sharing supports cross-cloud data access, but there are some limitations.
- Cross-cloud sharing must be explicitly enabled by the provider.
Fix:
✅ Check the allowed recipients for the share:
SHOW RECIPIENTS IN SHARE my_share;
✅ Ensure that the external workspace is using a compatible Unity Catalog version.
✅ For AWS-to-Azure sharing, verify that AWS PrivateLink or Azure Private Endpoints are used.
Step-by-Step Troubleshooting Guide
Step 1: Verify That Unity Catalog Is Enabled
SHOW CATALOGS;
- If empty, Unity Catalog is not enabled for the workspace.
Step 2: Check If a Metastore Is Assigned
SHOW METASTORES;
- If missing, assign a Unity Catalog metastore.
Step 3: List Available Shares and Recipients
SHOW SHARES;
SHOW RECIPIENTS IN SHARE my_share;
- Ensure the external user is listed as a recipient.
Step 4: Check Permissions for the Shared Table
SHOW GRANTS ON TABLE my_catalog.my_schema.my_table;
- If the external user does not have SELECT permissions, grant them access.
Step 5: Confirm That the Recipient Workspace Has Accepted the Share
- Check if the recipient can see shared data in their Databricks UI.
- If not, ensure they manually accept the shared table.
Best Practices for Sharing Tables With External Users in Unity Catalog
✅ Ensure External Users Have a Databricks Account That Supports Unity Catalog
- External users must have a Unity Catalog-enabled workspace.
✅ Grant Explicit Access to the Shared Table, Schema, and Catalog
GRANT USAGE ON CATALOG my_catalog TO SHARE my_share;
GRANT USAGE ON SCHEMA my_catalog.my_schema TO SHARE my_share;
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO SHARE my_share;
✅ Verify That External Users Have Accepted the Share
- Go to Databricks UI → Data → Shared Data → Accept Share.
✅ Use PrivateLink or Secure Network Configurations for Cross-Cloud Sharing
- Ensure AWS PrivateLink or Azure Private Endpoints are used for secure access.
Conclusion
If external users cannot access shared tables in Unity Catalog, ensure that:
✅ Unity Catalog is enabled in both the provider and recipient workspace.
✅ External users are explicitly added to the share.
✅ Correct permissions are granted on the catalog, schema, and table.
✅ The recipient workspace has accepted the share and configured authentication.
✅ Cross-cloud or cross-region sharing limitations are handled.
By following this guide, you can resolve sharing issues and ensure smooth external access to Unity Catalog tables in Databricks.