Common Unity Catalog migration mistakes, and how to avoid them
Most Unity Catalog migration problems appear during and after the move, not before it. Six mistakes, why each happens, and how to avoid it, with a checklist.
The mistakes that cost the most time in a Unity Catalog migration are rarely about copying tables. They sit in table history, views, compute that cannot run the old code, tools whose support status nobody checked, and the moment the old metastore is switched off. This article covers six of them. Each one is tied to a page of Databricks documentation, so you can check it against the version you run.
Preparation, meaning the inventory, identities, storage and code review, is covered in the article on preparing a move from Hive metastore to Unity Catalog. This article starts where that one stops: the move itself, and what follows it.
Hive metastore vs Unity Catalog: what changes
The per-workspace Hive metastore is described by Databricks as a legacy feature, and its tables do not benefit from the full set of security and governance features of Unity Catalog. In the three-level namespace it appears as a catalog called hive_metastore. Permissions inside it refer to the local users and groups of one workspace, while Unity Catalog is an account-level object whose permissions apply across workspaces, with lineage and audit built on the same model. Databricks recommends migrating the tables and the workloads that reference them. The details of the two models are in the preparation article above; the rest of this one is about what goes wrong.
Mistake 1: treating SYNC, CLONE and CTAS as interchangeable
What it looks like. A schema is upgraded with a single method applied to all its tables. Some tables fail to upgrade, or arrive without their history.
Why it happens. The methods cover different tables. SYNC upgrades external tables, and managed tables when they are stored outside workspace storage; it cannot upgrade Hive managed tables in workspace storage. Those need CREATE TABLE CLONE, which works on managed Delta tables and must be a deep clone when the source is the Hive metastore. A clone is a new table: table history is not migrated, so time travel to a point before the migration is not available on the new table. Tables that do not meet the CLONE requirements fall back to CREATE TABLE AS SELECT.
How to avoid it. Choose the method per table type, not per schema. List which reports, reconciliations or audits rely on time travel, and keep the old table, or a separate history store, for those. For an organisation that reconciles figures against earlier table versions, this is a business question to settle before the move, not a technical detail to find afterwards.
Mistake 2: forgetting views and partition commands
What it looks like. Reports break after the tables have moved, or a maintenance script that worked on a Hive table fails on the new one.
Why it happens. Views are not migrated directly. They have to be created again once the tables they reference exist in the same Unity Catalog metastore. Separately, Unity Catalog manages partitions differently from Hive, and Hive commands that manipulate partitions directly are not supported on Unity Catalog managed tables.
How to avoid it. Order the work by dependency: the tables, then the views that read them, then the reports that read the views. Search the code base for partition-level commands before the move and plan their replacement.
Mistake 3: running workloads on standard compute without checking the code
What it looks like. A job that ran before the migration fails after it, on the same code.
Why it happens. Standard access mode has documented limitations. The RDD API is not supported. In Scala, sc, spark.sparkContext and sqlContext are not supported, and Databricks recommends the spark session variable instead. R is not supported, and neither is Databricks Runtime for ML. The DBFS root and mounts do not support FUSE. For workloads that need these features, the documentation says to use dedicated compute.
How to avoid it. Search the code for these patterns before choosing the compute type for each job, and put the jobs that need them on dedicated compute deliberately, not after a failure. The code review described in the preparation article is the place to catch them.
Mistake 4: relying on a tool without knowing its support status
What it looks like. An automated upgrade stops half-way, and nobody on the project knows the tool well enough to continue by hand.
Why it happens. UCX is a Databricks Labs project, and Databricks recommends it for most workspace upgrade scenarios. The same documentation says it is provided for exploration, is not formally supported by Databricks, and carries no formal support SLA; issues go to GitHub, not to a support ticket. It also says that the code migration workflow shown in its diagram remains under development and is not yet available. The documentation recommends running the assessment more than once to find all incompatible entities.
How to avoid it. Use UCX for what it does well, the assessment and the repeatable group and table workflows, and plan for a person who can read its output and finish by hand what it does not finish. This is also the practical answer to the question of a Unity Catalog migration accelerator: the tool shortens the work of finding and moving objects, and the decisions about scope, order and acceptance stay with people. The wider set of free migration tools, phase by phase, is in Databricks migration accelerators.
Mistake 5: treating Hive metastore federation as the finish line
What it looks like. The migration is declared complete because all tables are visible in Unity Catalog, and a year later the legacy metastore is still on the query path.
Why it happens. Federation lets Unity Catalog govern tables that remain in a Hive metastore, and Databricks presents it as a way to migrate incrementally without changing code. It has limits. Writes through the foreign catalog are supported for the internal Hive metastore of a workspace, not for an external Hive metastore or AWS Glue. Features that belong to Unity Catalog managed tables, such as predictive optimization, do not apply to foreign tables. Databricks also notes that performance can be marginally worse, because both systems sit on the query path.
How to avoid it. Use federation as a bridge with an end date, and record in the plan which tables are still foreign and what moves them.
Mistake 6: dropping old tables too early, or switching legacy access off too late
What it looks like. Either a table that something still reads is dropped, or the legacy metastore stays reachable long after the move and the team runs two permission systems.
Why it happens. In the first case, nobody tested for dependencies. The documentation suggests revoking access to the old table and re-running the related queries and workloads, and it says to keep the old table while you rely on deprecation comments, if the source changed after a sync, or if you made a shallow clone, because a shallow clone references the data of the source table. In the second case, legacy access stays on by default until an administrator turns it off. Switching it off has consequences the documentation lists: jobs that query Hive-registered tables fail, jobs on Databricks Runtime below 13.3 LTS fail, running jobs continue but cannot restart on those clusters, and after 30 days the workspace permanently runs on Unity Catalog alone and direct access cannot be re-enabled. The page also states that Databricks is progressively disabling direct access for workspaces with no Hive metastore usage, and that legacy access might be disabled automatically starting in July 2026.
How to avoid it. Test dependencies by revoking, not by reading code. Upgrade jobs to Runtime 13.3 LTS or above before the switch, and put the date of the switch in the plan, so that the 30-day period is a decision, not a surprise.
A migration checklist for regulated teams
- Method chosen per table type, with the reason recorded; history needs identified before any clone.
- Views, reports and partition commands ordered after the tables they depend on.
- Code searched for RDD,
sc,sqlContext, R, ML runtime and DBFS root or mount access; dedicated compute assigned where needed. - A named person who can run and read the assessment tool, and finish by hand what it does not.
- Federated tables listed, each with the step that moves it.
- Old tables dropped after access was revoked and workloads re-run; jobs on Runtime 13.3 LTS or above before legacy access is switched off.
- Region decided: the Unity Catalog metastore is tied to a region. Databricks lists no region in Vietnam, so organisations in Vietnam usually look at Singapore, which affects cost (see Databricks pricing in Singapore vs US East).
- Lineage and audit logs switched on from the initial wave, because they are the evidence a regulator or auditor may ask for. The permissions model that follows is covered in Genie for business users.
- Which data may sit on a regional platform is a legal question for your own compliance team and counsel. Settle it before choosing which tables move; see Vietnam’s personal data law and the architecture for banks.
Where Sancire comes in
A free 90-minute Discovery Workshop is a way to check a migration plan against this list. The Migration Scan takes one week and produces the inventory, sequenced waves, risks and a fixed quote per wave. The upgrade itself, with the access model, lineage and audit coverage, is Unity Catalog Governance, from $35,000. For banks and insurers, the Data Zoning & Compliance Assessment, from $10,000, is the opening step, because the decision on which data goes to a regional platform precedes the decision on which tables move.
Sources, all public Databricks pages, read on 17 October 2026: Upgrade Hive tables and views to Unity Catalog (updated 6 October 2026); Use the UCX utilities to upgrade your workspace to Unity Catalog (6 October 2026); Disable access to the Hive metastore used by your Databricks workspace (6 October 2026); Work with the legacy Hive metastore alongside Unity Catalog (11 September 2026); Hive metastore federation (11 September 2026); Standard compute requirements and limitations (11 September 2026); Supported regions (11 September 2026); UCX on Databricks Labs (no date shown). Features and limits change between runtime versions; check the current documentation before planning.