Introduction

The SQL003 – Table Not Found error in Databricks indicates that the specified table does not exist or is inaccessible in the catalog, schema, or database you are querying. This error can occur in both Unity Catalog and Hive Metastore environments for several reasons, including misconfigured catalogs, incorrect table names, or missing permissions.

Common Causes and Fixes for SQL003 – Table Not Found

1. Incorrect Table Name or Schema

Symptoms:

• Error: “SQL003: Table not found.”
• The table does not exist in the specified schema or catalog.

Causes:

• The table name or schema name is incorrect.
• The table might exist in a different catalog or database.

Fix:
✅ Verify the correct table and schema names:

SHOW TABLES IN my_catalog.my_schema;

✅ Use the fully qualified table name:

SELECT * FROM my_catalog.my_schema.my_table;

✅ If unsure of the catalog, try listing all catalogs and schemas:

SHOW CATALOGS;
SHOW SCHEMAS IN my_catalog;

2. Unity Catalog Is Not Enabled or Misconfigured

Symptoms:

• Error: “SQL003: Table not found.”
• Unity Catalog is not available or not properly configured.

Causes:

• Unity Catalog is not enabled for the cluster or SQL Warehouse.
• The table is in a Hive Metastore but being queried as a Unity Catalog table.

Fix:
✅ Ensure Unity Catalog is enabled for the cluster:

• Go to Clusters → Advanced Options and enable Unity Catalog.
  ✅ Verify the metastore assignment:

SHOW METASTORES;

✅ Switch back to Hive Metastore if needed:

USE DATABASE hive_metastore.default;

3. Table Has Been Dropped or Not Created

Symptoms:

• Error: “SQL003: Table not found.”
• The table was available earlier but now cannot be found.

Causes:

• The table may have been dropped.
• The table creation process may have failed or is incomplete.

Fix:
✅ Check the history of the table (if using Delta):

DESCRIBE HISTORY delta.`/mnt/delta/my_table/`;

✅ Recreate the table if necessary:

CREATE TABLE my_catalog.my_schema.my_table (id INT, name STRING);

4. Permissions Issue

Symptoms:

• Error: “SQL003: Table not found.”
• Table exists, but the user cannot access it.

Causes:

• User lacks permissions to access the catalog, schema, or table.
• The table permissions were recently changed.

Fix:
✅ Check table permissions:

SHOW GRANTS ON TABLE my_catalog.my_schema.my_table;

✅ Grant the necessary permissions:

GRANT SELECT ON TABLE my_catalog.my_schema.my_table TO `user@example.com`;

5. Table Exists in Another Catalog

Symptoms:

• Error: “SQL003: Table not found.”
• The table is present, but not in the queried catalog.

Causes:

• The table was created in a different catalog or schema.

Fix:
✅ Check all available catalogs and schemas:

SHOW TABLES IN hive_metastore.default;
SHOW TABLES IN my_catalog.another_schema;

✅ Query using the fully qualified table name:

SELECT * FROM hive_metastore.default.my_table;

Step-by-Step Troubleshooting Guide

1. Verify Table Existence

SHOW TABLES IN my_catalog.my_schema;

2. Check for Correct Metastore and Catalog

SHOW METASTORES;

3. Ensure Proper Permissions

SHOW GRANTS ON TABLE my_catalog.my_schema.my_table;

4. Use Fully Qualified Table Names

SELECT * FROM my_catalog.my_schema.my_table;

Best Practices to Avoid SQL003 – Table Not Found

1. Always use fully qualified table names (catalog.schema.table) to avoid confusion between Unity Catalog and Hive Metastore.
2. Verify the table’s existence before querying.
3. Grant necessary permissions to users and groups.
4. Monitor table changes and metastore configurations.
5. If using Delta Lake, check the Delta log history for recent table operations.

Conclusion

The SQL003 – Table Not Found error in Databricks usually results from misconfigured catalogs, incorrect table names, or missing permissions. By following these troubleshooting steps and best practices, you can quickly resolve the issue and ensure seamless querying in Databricks.