Introduction

The TestUC3002 – Schema Not Found error occurs in Databricks Unity Catalog when a requested schema does not exist, or the user lacks the necessary permissions to access it. This error can prevent query execution, data exploration, and table management, leading to workflow interruptions.

🚨 Common symptoms of TestUC3002 – Schema Not Found:

• Error: “TestUC3002 – Schema Not Found” while running SQL commands.
• Cannot access or list schemas in a Unity Catalog catalog.
• Tables and schemas do not appear in the Databricks SQL UI.
• SHOW SCHEMAS returns an empty result.

Common Causes and Fixes for TestUC3002

1. Schema Does Not Exist in the Catalog

Symptoms:

• Error: “Schema not found” when running USE SCHEMA.
• SHOW SCHEMAS returns no results.

Causes:

• The requested schema has not been created in Unity Catalog.
• Typographical errors in schema names.
• Schema was dropped or not properly created.

Fix:
✅ Check available schemas in the catalog:

SHOW SCHEMAS IN my_catalog;

✅ Create the missing schema if it does not exist:

CREATE SCHEMA my_catalog.my_schema;

✅ Ensure the correct catalog and schema names are used:

USE CATALOG my_catalog;
USE SCHEMA my_schema;

2. Insufficient Permissions on the Schema

Symptoms:

• Error: “Permission denied while accessing schema.”
• Cannot read or write to tables in the schema.

Causes:

• The user does not have the required permissions to access the schema.
• Schema-level permissions were not granted to the current user or group.

Fix:
✅ Check current user permissions:

SHOW GRANTS ON SCHEMA my_catalog.my_schema;

✅ Grant the necessary permissions:

GRANT USAGE ON SCHEMA my_catalog.my_schema TO `user@example.com`;
GRANT SELECT ON ALL TABLES IN SCHEMA my_catalog.my_schema TO `user@example.com`;

3. Incorrect Cluster or SQL Warehouse Configuration

Symptoms:

• Error: “Schema not found” in a Databricks notebook.
• SQL Warehouses cannot access Unity Catalog schemas.

Causes:

• Cluster is not configured for Unity Catalog.
• Legacy clusters using Hive Metastore do not support Unity Catalog schemas.

Fix:
✅ Ensure your cluster is Unity Catalog-enabled:

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

✅ For SQL Warehouses, enable Unity Catalog:

1. Go to Databricks UI → SQL Warehouses → Edit → Advanced Settings.
2. Ensure Unity Catalog is supported.

4. Schema Exists in a Different Catalog

Symptoms:

• Error: “Schema not found” despite knowing it exists.
• Schema appears in a different catalog.

Causes:

• Unity Catalog organizes schemas by catalog, and the schema might exist in another catalog.
• USE CATALOG command was not executed before accessing the schema.

Fix:
✅ List schemas across catalogs:

SHOW CATALOGS;
SHOW SCHEMAS IN catalog_name;

✅ Switch to the correct catalog:

USE CATALOG correct_catalog;

5. Schema Conflict with Hive Metastore

Symptoms:

• Error: “Schema not found” after migrating from Hive Metastore to Unity Catalog.
• Legacy tables do not appear in Unity Catalog schemas.

Causes:

• Unity Catalog does not automatically migrate schemas from Hive Metastore.
• Tables are still linked to the Hive Metastore.

Fix:
✅ Convert Hive Metastore tables to Unity Catalog:

ALTER TABLE hive_metastore.default.my_table CONVERT TO DELTA;

✅ Create the schema in Unity Catalog:

CREATE SCHEMA my_catalog.my_schema;

Step-by-Step Troubleshooting Guide

1. Check Available Schemas in the Catalog

SHOW SCHEMAS IN my_catalog;

2. Verify Permissions on the Schema

SHOW GRANTS ON SCHEMA my_catalog.my_schema;

3. Ensure the Cluster or SQL Warehouse Supports Unity Catalog

• Restart the cluster and enable Unity Catalog support.

4. List Schemas Across Multiple Catalogs

SHOW CATALOGS;
SHOW SCHEMAS IN each_catalog;

5. Check for Typos or Incorrect Schema Names

• Verify schema and catalog names in your SQL commands.

Best Practices to Avoid TestUC3002 – Schema Not Found

✅ Always Specify Catalog and Schema Names Explicitly

USE CATALOG my_catalog;
USE SCHEMA my_schema;

✅ Grant Permissions at the Schema Level

• Ensure users have USAGE and SELECT permissions on schemas.

✅ Enable Unity Catalog for All Clusters and Warehouses

• Avoid using legacy clusters with Hive Metastore.

✅ Regularly Audit Schemas and Permissions

• Use SHOW GRANTS to monitor schema access.

Conclusion

The TestUC3002 – Schema Not Found error in Databricks Unity Catalog is typically caused by missing schemas, insufficient permissions, or misconfigured clusters. By checking available schemas, ensuring proper permissions, and using Unity Catalog-enabled clusters, you can resolve this issue and access your data efficiently.

Mohammad Gufran Jahangir