Introduction

The TestUC2002 – Metastore Already Exists error occurs when attempting to create or assign a new metastore to a Databricks workspace that already has an existing metastore. This can block further configuration of Unity Catalog and lead to conflicts in metadata management.

🚨 Common symptoms of TestUC2002 – Metastore Already Exists:

• Error: “TestUC2002 – Metastore already exists for this workspace.”
• Cannot create or assign a new metastore.
• Unity Catalog commands fail due to conflicting metastore configurations.

This guide will help you understand the causes and provide actionable steps to resolve the TestUC2002 error.

Common Causes and Fixes for TestUC2002

1. Metastore Already Assigned to Workspace

Symptoms:

• Error: “Metastore already exists for this workspace.”
• SHOW METASTORES displays an assigned metastore.

Causes:

• The workspace already has an active metastore assigned.
• Attempting to create a duplicate metastore for the same workspace.

Fix:
✅ Check if a metastore is already assigned:

SHOW METASTORES;

✅ If a metastore exists, do not create a new one. Use the existing metastore:

USE METASTORE my_metastore;

✅ If you need a new metastore, detach the existing one (Admin-only):

databricks unity-catalog metastores unassign --workspace-id <workspace-id>

2. Attempting to Recreate a Metastore with the Same Name

Symptoms:

• Error: “Metastore already exists with this name.”
• Cannot create a new metastore with a previously used name.

Causes:

• The metastore name is already in use in Unity Catalog.
• Old metastore records were not cleaned up after deletion.

Fix:
✅ List existing metastores to check for duplicates:

SHOW METASTORES;

✅ Use a different name for the new metastore:

databricks unity-catalog metastores create --name new_metastore_name --region <region>

✅ If the old metastore is no longer needed, delete it (Admin-only):

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

3. Multiple Workspaces Sharing the Same Metastore

Symptoms:

• Metastore conflicts across different workspaces.
• Error: “Cannot assign metastore: already used by another workspace.”

Causes:

• Attempting to assign the same metastore to multiple workspaces without proper configuration.
• Cluster configurations are not consistent across workspaces.

Fix:
✅ Ensure the same metastore is compatible with multiple workspaces:

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

✅ For multiple workspaces, configure a shared metastore:

• Ensure storage access policies and permissions are set correctly.

Step-by-Step Troubleshooting Guide

Step 1: Check Assigned Metastore

SHOW METASTORES;

• If a metastore is already assigned, avoid creating a new one.

Step 2: Detach the Existing Metastore (If Necessary)

databricks unity-catalog metastores unassign --workspace-id <workspace-id>

Step 3: Create a New Metastore

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

Step 4: Reassign the New Metastore

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

Best Practices to Avoid TestUC2002 Errors

✅ Use One Metastore Per Workspace

• Avoid creating multiple metastores for the same workspace.

✅ Check Existing Metastores Before Creating a New One

SHOW METASTORES;

✅ Detach Old Metastores Properly Before Creating New Ones

databricks unity-catalog metastores unassign --workspace-id <workspace-id>

✅ Coordinate Metastore Usage for Multi-Workspace Environments

• Ensure consistent permissions and storage access for shared metastores.

Conclusion

The TestUC2002 – Metastore Already Exists error typically occurs due to conflicting metastore configurations or duplicate assignments. By following the steps to check existing metastores, detach old ones, and create or assign new metastores, you can resolve this error and maintain a consistent Unity Catalog setup.