hasura error: cannot apply migration - inconsistent metadata after hasura upgrade

TL;DR

The upgrade changed what hasura expects in its metadata, so objects tracked under the old version are now inconsistent and block migrations. Reload the metadata to let hasura re-evaluate, remove or repair the objects it flags as inconsistent, and then apply the migrations. Always snapshot the metadata first: hasura metadata export before you touch anything.

The query

hasura error: cannot apply migration - inconsistent metadata after hasura upgrade

Use this when

• hasura migrate apply fails with "inconsistent metadata"
• Inconsistent objects appeared after a hasura upgrade
• The console shows metadata inconsistency errors blocking deploys
• An agent upgraded hasura without reloading metadata

Not for

• Migration SQL that fails on the database (fix the SQL)
• Permission or role errors on tracked tables (fix grants)
• A hasura instance that never had metadata applied (apply it fresh)

Steps

1. Snapshot the current metadata

hasura metadata export

Expected output: metadata.yaml written (or printed) capturing the current state. This is your rollback if the repair goes sideways.

2. Reload the metadata and list inconsistent objects

hasura metadata reload

Then check the console or run:

hasura metadata inconsistency status

Expected output: a list of the inconsistent objects with reasons, e.g. a table or function whose definition changed shape in the new version.

3. Repair or drop the inconsistent objects

For each flagged object: if the underlying database object still exists and is correct, untrack and re-track it (or fix the metadata entry by hand). If it references something the upgrade removed, drop it from the metadata. Work through the list until the status is clean.

Expected output: inconsistency status reports no inconsistent objects.

4. Re-apply the migrations

hasura migrate apply --all-databases

Expected output: migrations apply cleanly now that the metadata no longer blocks them. If a migration still fails, it is a SQL problem, not a metadata problem: fix the SQL.

5. Pin the upgrade procedure for next time

The agent's hasura upgrade runbook becomes: export metadata, upgrade, reload, clear inconsistencies, then migrate. Never upgrade the server and the metadata in one blind step.

Expected output: the next upgrade follows the sequence and does not strand the instance in an inconsistent state.

Tool compatibility

hasura graphql-engine v2.x. metadata export/reload/inconsistency commands are stable across v2.

Variant phrasings

hasura cannot apply migration inconsistent metadata

Steps 1 through 4: snapshot, reload, clear, apply.

hasura inconsistent metadata after upgrade

Step 2 is the diagnosis: reload first, because many "inconsistencies" are just stale evaluations against the new version.

hasura metadata inconsistency status clean but migrate fails

Step 4: once metadata is clean, remaining failures are SQL problems in the migration files.

Why it happens

Hasura keeps a metadata catalogue describing tracked tables, relationships, and permissions, versioned alongside the server. An upgrade can change the expected metadata shape, so objects valid under the old version fail validation under the new one. Hasura blocks migrations while inconsistent because applying schema changes against a broken catalogue risks corrupting the API layer.

Edge cases

• Export before reload: on rare upgrades the reload itself drops objects it cannot parse, and the export is the only way back.
• If the same migration set must run against hasura instances on different versions, upgrade every instance first: metadata is not portable across major version gaps.
• Inconsistent computed fields and remote schemas are the most common flags after upgrades: check those first.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SHwWdzC7z5-Bw8v0BbY8dw