Introduction

The TestUC2005 – Metastore Version Mismatch error in Databricks Unity Catalog indicates a version incompatibility between the Unity Catalog metastore and the Databricks runtime or cluster configuration. This error typically arises when the metastore version does not match the supported version for the Databricks runtime, preventing the successful connection or management of catalog operations.

🚨 Common symptoms of TestUC2005 – Metastore Version Mismatch:

• Error: “TestUC2005 – Metastore Version Mismatch” when connecting to Unity Catalog.
• Failed cluster startup or inability to attach Unity Catalog to the workspace.
• Tables and schemas not visible in Unity Catalog.
• USE CATALOG or SHOW METASTORES commands fail.

Common Causes and Fixes for TestUC2005

1. Incompatible Databricks Runtime Version

Symptoms:

• Error: “Metastore Version Mismatch” when running Unity Catalog commands.
• Cluster fails to start with Unity Catalog enabled.

Causes:

• The Databricks runtime version does not support the current Unity Catalog metastore version.
• Legacy runtimes are not compatible with Unity Catalog.

Fix:
✅ Use a supported Databricks runtime version for Unity Catalog:

• Unity Catalog requires Databricks Runtime 11.3 or higher.
• Go to Databricks UI → Clusters → Edit Cluster and upgrade the runtime version.

✅ Check the current cluster runtime version:

databricks clusters get --cluster-id <cluster-id>

✅ Upgrade the runtime to a compatible version:

databricks clusters edit --cluster-id <cluster-id> --runtime-version "11.3.x-cpu-ml-scala2.12"

2. Outdated Unity Catalog Metastore

Symptoms:

• Error: “Metastore Version Mismatch” during metastore assignment.
• Unity Catalog commands return errors indicating outdated features.

Causes:

• The Unity Catalog metastore is running an outdated version that does not support the current Databricks runtime.
• New features or commands are not recognized.

Fix:
✅ Check the current metastore version:

SHOW METASTORES;

✅ Upgrade the Unity Catalog metastore:

databricks unity-catalog metastores upgrade --metastore-id <metastore-id>

✅ Verify the metastore version compatibility with your Databricks runtime:

• Refer to the Databricks release notes to confirm the supported Unity Catalog versions.

3. Multiple Metastores with Conflicting Versions

Symptoms:

• Error: “Metastore Version Mismatch” when switching catalogs.
• Different catalogs behave inconsistently in the same workspace.

Causes:

• The workspace is linked to multiple metastores with different versions.
• Conflicting schema versions across metastores cause errors.

Fix:
✅ List all metastores linked to the workspace:

SHOW METASTORES;

✅ Ensure only one metastore is assigned:

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

✅ Detach conflicting metastores if necessary:

databricks unity-catalog metastores unassign --metastore-id <conflicting-metastore-id>

4. Incorrect Metastore Configuration

Symptoms:

• Error: “Invalid metastore configuration or metadata.”
• Tables and schemas do not appear in Unity Catalog.

Causes:

• The metastore configuration is corrupted or incomplete.
• Metadata schema mismatches between the Databricks workspace and the metastore.

Fix:
✅ Check the metastore configuration:

databricks unity-catalog metastores get --metastore-id <metastore-id>

✅ Reconfigure the metastore with the correct parameters:

databricks unity-catalog metastores update --metastore-id <metastore-id> --region <region> --s3-bucket <bucket-name>

✅ If the configuration is corrupted, create a new metastore:

databricks unity-catalog metastores create --region <region> --s3-bucket <new-bucket-name>

Step-by-Step Troubleshooting Guide

Step 1: Check Databricks Runtime Version

Ensure you are using Databricks Runtime 11.3 or higher.

databricks clusters get --cluster-id <cluster-id>

Step 2: Verify Metastore Version

SHOW METASTORES;

If outdated, upgrade the metastore to the latest version.

Step 3: Ensure Correct Metastore Assignment

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

Step 4: Resolve Multiple Metastore Conflicts

List and detach conflicting metastores:

databricks unity-catalog metastores unassign --metastore-id <conflicting-metastore-id>

Best Practices to Avoid Metastore Version Mismatch

✅ Keep Databricks Runtime and Metastore Versions Aligned

• Always use a compatible runtime version for your Unity Catalog.
• Regularly update your metastore to the latest version.

✅ Avoid Multiple Metastore Assignments

• Assign only one metastore per workspace to prevent conflicts.

✅ Monitor Metastore Updates and Databricks Release Notes

• Stay informed about new Unity Catalog versions and runtime compatibility.

Conclusion

The TestUC2005 – Metastore Version Mismatch error in Unity Catalog arises from incompatibilities between Databricks runtime and metastore versions. By ensuring runtime compatibility, updating the metastore, and resolving configuration conflicts, you can prevent this error and ensure smooth Unity Catalog operations.