Introduction
Delta Sharing in Unity Catalog allows secure data sharing across Databricks workspaces, organizations, and external clients without copying data. However, you may encounter issues when trying to share Unity Catalog tables using Delta Sharing, such as:
🚨 Common Delta Sharing problems in Unity Catalog:
- Error: “Delta Sharing is not enabled for this metastore.”
- Error: “Table is not eligible for sharing.”
- **Shared tables do not appear in the recipient workspace._
- **Delta Sharing works for some tables but not others._
This guide will help you troubleshoot why Unity Catalog tables cannot be shared using Delta Sharing and how to fix these issues.
1. Verify That Delta Sharing Is Enabled for the Metastore
Symptoms:
- Error: “Delta Sharing is not enabled for this metastore.”
- The Delta Sharing UI is missing from Databricks.
Causes:
- Delta Sharing is not enabled for the Unity Catalog metastore.
- Your Databricks workspace does not support Delta Sharing.
Fix:
✅ Check if Delta Sharing is enabled for the metastore:
SHOW METASTORES;
✅ If Delta Sharing is not enabled, enable it for your metastore (Admin Required):
databricks unity-catalog metastores update --metastore-id <metastore-id> --delta-sharing-scope "INTERNAL_AND_EXTERNAL"
✅ Verify Delta Sharing settings:
databricks unity-catalog metastores get --metastore-id <metastore-id>
- Ensure
deltaSharingScope
is set to"INTERNAL_AND_EXTERNAL"
or"INTERNAL_ONLY"
.
✅ Restart your Databricks cluster after enabling Delta Sharing.
2. Ensure That Tables Are in Unity Catalog (Not Hive Metastore)
Symptoms:
- Error: “Table is not eligible for sharing.”
- Only some tables are visible for sharing.
Causes:
- Only Unity Catalog tables can be shared using Delta Sharing.
- Hive Metastore tables cannot be shared.
Fix:
✅ Check if the table exists in Unity Catalog or Hive Metastore:
SHOW CATALOGS;
SHOW TABLES IN hive_metastore.default;
SHOW TABLES IN my_catalog.my_schema;
✅ If the table is in Hive Metastore, migrate it to Unity Catalog:
ALTER TABLE hive_metastore.default.my_table CONVERT TO DELTA;
CREATE TABLE my_catalog.my_schema.my_table AS SELECT * FROM hive_metastore.default.my_table;
✅ Ensure all tables for sharing are stored in Unity Catalog.
3. Check Permissions for Delta Sharing
Symptoms:
- Error: “Permission denied: Cannot share table.”
- The shared table does not appear in the recipient’s workspace.
Causes:
- The user does not have permission to share tables.
- The recipient does not have access to the shared catalog or schema.
Fix:
✅ Grant SHARE permissions to the user:
GRANT CREATE SHARE ON METASTORE TO `user@example.com`;
✅ Ensure the table owner has permission to share the table:
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO `user@example.com`;
✅ If the recipient does not see the table, verify their access:
SHOW RECIPIENTS;
✅ Grant usage permission on the catalog and schema:
GRANT USE CATALOG ON CATALOG my_catalog TO `user@example.com`;
GRANT USE SCHEMA ON SCHEMA my_catalog.my_schema TO `user@example.com`;
4. Verify That Delta Sharing Recipients Are Configured Correctly
Symptoms:
- Shared tables do not appear in the recipient workspace.
- The recipient cannot query the shared table.
Causes:
- The recipient was not properly added to the Delta Sharing agreement.
- The shared table was not activated by the recipient.
Fix:
✅ Check if the recipient exists in Delta Sharing:
SHOW RECIPIENTS;
✅ Create a new recipient if needed:
CREATE RECIPIENT my_recipient USING IDENTITY `recipient@example.com`;
✅ Share a table with the recipient:
CREATE SHARE my_share;
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO SHARE my_share;
ADD RECIPIENT TO SHARE my_share my_recipient;
✅ If the recipient does not see the table, ask them to list shared tables:
SHOW SHARES;
5. Ensure That the Shared Table Has the Correct Format
Symptoms:
- Error: “Table format not supported for sharing.”
- Some tables can be shared, while others cannot.
Causes:
- Only Delta tables can be shared using Delta Sharing.
- Parquet, CSV, or other file formats are not supported.
Fix:
✅ Check if the table is a Delta table:
DESCRIBE DETAIL my_catalog.my_schema.my_table;
✅ If the table is not in Delta format, convert it:
ALTER TABLE my_catalog.my_schema.my_table CONVERT TO DELTA;
✅ Reattempt sharing after conversion.
6. Resolve Issues With External Recipients
Symptoms:
- External users cannot access the shared table.
- Error: “Recipient not found.”
Causes:
- The recipient email is incorrect or not associated with a Databricks workspace.
- The recipient organization has not accepted the Delta Sharing agreement.
Fix:
✅ Ensure the correct email address is used for the recipient:
SHOW RECIPIENTS;
✅ Resend the sharing invitation if needed:
ALTER RECIPIENT my_recipient SET COMMENT 'Resending invitation';
✅ Verify the recipient has accepted the share invitation.
7. Troubleshooting Step-by-Step
Step 1: Verify That Delta Sharing Is Enabled
databricks unity-catalog metastores get --metastore-id <metastore-id>
- If
deltaSharingScope
is"NONE"
, enable it using:
databricks unity-catalog metastores update --metastore-id <metastore-id> --delta-sharing-scope "INTERNAL_AND_EXTERNAL"
Step 2: Check That the Table Is in Unity Catalog
SHOW TABLES IN my_catalog.my_schema;
- If missing, migrate the table from Hive Metastore.
Step 3: Verify Permissions
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO SHARE my_share;
Step 4: Ensure the Table Is in Delta Format
DESCRIBE DETAIL my_catalog.my_schema.my_table;
- If not Delta format, convert it.
Step 5: Verify Recipient Configuration
SHOW RECIPIENTS;
- If missing, add the recipient again.
Best Practices for Delta Sharing in Unity Catalog
✅ Ensure Unity Catalog Is Enabled and Metastore Supports Delta Sharing
databricks unity-catalog metastores update --metastore-id <metastore-id> --delta-sharing-scope "INTERNAL_AND_EXTERNAL"
✅ Only Share Delta Tables (Not Parquet, CSV, or Other Formats)
ALTER TABLE my_catalog.my_schema.my_table CONVERT TO DELTA;
✅ Use the Correct Permissions for Data Sharing
GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO SHARE my_share;
✅ Ensure Recipients Have Accepted the Share Invitation
SHOW RECIPIENTS;
Conclusion
If Unity Catalog tables cannot be shared using Delta Sharing, check:
✅ Delta Sharing is enabled for the metastore.
✅ The table is stored in Unity Catalog (not Hive Metastore).
✅ The table is in Delta format.
✅ Correct permissions are assigned for sharing.
✅ Recipients are properly configured and can accept the share.
By following this guide, you can successfully share Unity Catalog tables using Delta Sharing in Databricks.