Introduction

The TestUC3005 – Invalid Catalog or Schema Name error in Databricks Unity Catalog typically indicates a problem with incorrect catalog or schema references in your SQL queries or configurations. This error can occur when attempting to access a non-existent catalog or schema, or if the catalog/schema is not properly assigned to the Unity Catalog metastore.

🚨 Common Symptoms:

• Error: “TestUC3005 – Invalid Catalog or Schema Name.”
• Queries fail when using USE CATALOG or USE SCHEMA.
• Cannot access tables in specific schemas or catalogs.
• Tables appear missing despite being created earlier.

Common Causes and Fixes for TestUC3005

1. Catalog or Schema Does Not Exist

Symptoms:

• Error: “Catalog does not exist.”
• Error: “Schema not found in the specified catalog.”
• Running SHOW CATALOGS; returns an empty list or does not show the expected catalog.

Causes:

• The specified catalog or schema does not exist in Unity Catalog.
• The catalog was not properly created or assigned to the metastore.
• Typographical errors in the catalog or schema name.

Fix:
✅ Check available catalogs and schemas:

SHOW CATALOGS;
SHOW SCHEMAS IN catalog_name;

✅ Create the catalog or schema if it doesn’t exist:

CREATE CATALOG my_catalog;
CREATE SCHEMA my_catalog.my_schema;

✅ Ensure the correct catalog or schema name is used in queries:

USE CATALOG my_catalog;
USE SCHEMA my_catalog.my_schema;

2. Catalog Not Assigned to the Unity Catalog Metastore

Symptoms:

• Error: “Invalid Catalog: The catalog is not assigned to any metastore.”
• Catalogs appear missing despite being previously created.

Causes:

• The catalog was created in a different workspace not linked to the current Unity Catalog metastore.
• The metastore assignment was removed or not configured correctly.

Fix:
✅ Check the current metastore:

SHOW METASTORES;

✅ Assign the catalog to the correct metastore:

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

✅ Verify that the catalog is associated with the metastore:

DESCRIBE CATALOG my_catalog;

3. Insufficient Permissions on the Catalog or Schema

Symptoms:

• Error: “Permission denied: Cannot access catalog or schema.”
• Users cannot list or access schemas and tables.

Causes:

• The user does not have the required permissions to access the catalog or schema.
• No privileges have been granted for the catalog or schema.

Fix:
✅ Grant the necessary permissions:

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

✅ Check current permissions:

SHOW GRANTS ON CATALOG my_catalog;

4. Using Legacy Hive Metastore Instead of Unity Catalog

Symptoms:

• Error: “Invalid catalog or schema name.”
• Cannot find tables that were created in Hive Metastore.

Causes:

• The query is attempting to access tables in the legacy Hive Metastore.
• The cluster is not configured to use Unity Catalog.

Fix:
✅ Ensure the cluster is configured to use Unity Catalog:

1. Go to Databricks UI → Clusters → Edit Cluster.
2. Enable Unity Catalog support in the advanced options.
3. Restart the cluster.

✅ Migrate Hive Metastore tables to Unity Catalog:

ALTER TABLE hive_metastore.default.my_table CONVERT TO DELTA;

5. Typographical Errors in Catalog or Schema Name

Symptoms:

• Error: “Catalog or schema name not found.”
• The query works intermittently or with different names.

Causes:

• Typographical errors in the catalog or schema name.
• Case sensitivity issues in schema or catalog references.

Fix:
✅ Double-check catalog and schema names:

SHOW CATALOGS;
SHOW SCHEMAS IN my_catalog;

✅ Use the exact names from the SHOW CATALOGS and SHOW SCHEMAS output.

Step-by-Step Troubleshooting Guide

1. Verify Available Catalogs and Schemas

SHOW CATALOGS;
SHOW SCHEMAS IN my_catalog;

2. Check Metastore Configuration

SHOW METASTORES;

3. Verify Permissions

SHOW GRANTS ON CATALOG my_catalog;

4. Ensure Unity Catalog Support on the Cluster

• Enable Unity Catalog in the cluster settings and restart the cluster.

Best Practices to Avoid TestUC3005 – Invalid Catalog or Schema Name

✅ Create and Manage Catalogs Properly

• Use CREATE CATALOG and CREATE SCHEMA to manage catalog structure.

✅ Use the Correct Metastore for Each Workspace

• Ensure all workspaces are linked to the correct Unity Catalog metastore.

✅ Grant Permissions for Access

• Always grant necessary privileges to users and groups for each catalog or schema.

✅ Migrate Legacy Hive Metastore Tables to Unity Catalog

• Use Unity Catalog for centralized governance and avoid legacy Hive Metastore conflicts.

Conclusion

The TestUC3005 – Invalid Catalog or Schema Name error in Databricks Unity Catalog is often caused by non-existent catalogs, misconfigurations, or insufficient permissions. By following the steps to verify catalogs, check metastore assignments, and grant the appropriate permissions, you can resolve this error and ensure seamless access to Unity Catalog resources.