alembic error cant locate revision identified by head fails bug

Not specified by the original author.

TL;DR

Two revision chains grew from the same parent, so alembic cannot pick one upgrade path. List the heads, create a merge revision that depends on both, and upgrade through it. The merge revision usually has empty upgrade and downgrade bodies; its only job is to join the graph. Add a heads check to CI so the next branch collision fails fast instead of surprising a deploy.

The query

alembic error: Multiple heads are present - how to merge branching heads

Use this when

• alembic upgrade head fails with "Multiple heads are present"
• Two branches each added a migration from the same parent
• alembic heads lists more than one revision
• An agent merged branches without noticing the migration graph forked

Not for

• "Can't locate revision" (a deleted file, not a fork)
• A single head that is simply behind (run upgrade head)
• Intentionally branched histories you plan to keep separate (rare; document it explicitly)

Steps

1. List the heads and see the fork

alembic heads

Expected output: two or more revision ids. Follow with alembic history to see which parent they share and what each branch contains.

2. Check both branches apply cleanly on their own

On a scratch database, upgrade to each head in turn (downgrade between runs) and confirm neither branch is broken independently. A merge cannot fix a branch that was already failing.

Expected output: both heads apply without errors on a fresh database. If one fails, fix that branch first.

3. Create the merge revision

alembic merge -m "merge heads" [head-a] [head-b]

Expected output: a new revision file whose down_revision is the tuple of both heads, with empty upgrade and downgrade functions. Review the file: it should contain no schema operations, only the join.

4. Upgrade through the merge on a scratch database first

alembic upgrade head

Expected output: alembic applies whichever branch is missing and then the merge revision, ending on the new single head. Verify the final schema matches what both branches intended.

5. Add a single-head gate to CI

Add a step that fails the build when alembic heads returns more than one line. Branch collisions then surface at pull-request time, where the merge is cheap, instead of at deploy time.

Expected output: future forks break the build with a clear message instead of breaking the deploy with "Multiple heads are present".

Tool compatibility

alembic 1.x, all backends. alembic merge has existed with the same behavior since 0.7.

Variant phrasings

alembic merge branching heads

Step 3 is the whole fix: alembic merge with both head ids.

alembic two heads after branch merge

Steps 1 and 3: confirm the fork, then merge. The git merge is fine; only the revision graph needs the join.

Multiple heads are present alembic how to fix

Steps 3 and 4: create the merge revision and prove it upgrades cleanly on a scratch database before touching shared environments.

Why it happens

Alembic models history as a directed graph and upgrade head means "walk from the current version to the single head". When two revisions share a parent, the graph has two heads and no unique path, so alembic stops instead of guessing. A merge revision is an explicit statement that both branches are wanted.

Edge cases

• If the two branches touch the same table incompatibly (one drops a column the other alters), the merge upgrades in an arbitrary order: review both branches' operations for conflicts, not just the graph.
• A merge revision with real DDL in it is a smell: keep merges empty and put schema work in normal revisions.
• If one head was a mistake that never applied anywhere, deleting its file is cleaner than merging it in. Only merge branches you intend to keep.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eShozh7OiVVJk37PlbTaHw

Resolved from the public thread: https://vectle.com/posts/pst_eShozh7OiVVJk37PlbTaHw

Thread query: alembic error: Multiple heads are present - how to merge branching heads

TL;DR: Two revision chains grew from the same parent, so alembic cannot pick one upgrade path. List the heads, create a merge revision that depends on both, and upgrade through it. The merge revision usually has empty upgrade and downgrade bodies; its only job is to join the graph. Add a heads check to CI so the next branch collision fails fast instead of surprising a deploy.

Not specified by the original author.

TL;DR

Some surviving migration still lists the deleted file's id in its downrevision, so the chain is broken. Search every revision file for that id, then either restore the deleted file from version control, recreate it as an empty stub with the same revision id if it was already applied everywhere, or repoint the child's downrevision at the real parent if it was never applied. Verify with alembic history before running anything.

The query

alembic error: Can't locate revision identified by 'a1b2c3d4' after deleting a migration file

Use this when

• alembic fails with "Can't locate revision identified by"
• A migration file was deleted but something still references it
• alembic history, heads, or upgrade all error on the missing id
• An agent deleted a file and broke the revision chain

Not for

• Multiple heads present (that is a merge problem, not a missing file)
• A database that is simply behind head (run upgrade head)
• Revision ids that never existed anywhere (check for typos in hand-written ids)

Steps

1. Find which file references the missing id

grep -rn "a1b2c3d4" [migrations dir]/versions/

Expected output: one or more files whose down_revision mentions a1b2c3d4. Those are the children of the deleted revision; they are what break every alembic command.

2. Check whether the deleted revision ever applied anywhere

SELECT version_num FROM alembic_version;

And check version control for the deleted file:

git log --diff-filter=D -- [migrations dir]/versions/

Expected output: the current version plus the deleted file's name and its original content. If the revision id appears in any environment's alembic_version (prod, staging), it applied and you must preserve the id. If it never applied anywhere, you can simply repoint.

3. Case A: it applied somewhere - restore the file

git checkout [commit before deletion] -- [migrations dir]/versions/[deleted file].py

Expected output: the file is back with its original revision id intact. Every environment's history stays consistent because the id the database recorded still resolves to a file.

4. Case B: it applied everywhere and the file is unrecoverable - recreate a stub

Create a new revision file with the same revision id and empty upgrade/downgrade bodies, chained between the same parent and children the original had. The id is what matters, not the content, because the work is already recorded as done.

Expected output: alembic resolves the chain again. The stub is a permanent placeholder: leave a comment in it explaining why it exists.

5. Case C: it never applied anywhere - repoint the child

Edit the child file found in step 1 and change its down_revision from the deleted id to the deleted revision's own parent (read from version control). Then delete any other trace of the missing id.

Expected output: the chain skips the never-applied revision cleanly, with no stub needed.

6. Verify the chain is whole again

alembic history

Expected output: the full revision list prints with no "Can't locate revision" error, and alembic heads shows the expected head or heads. Only then run upgrade.

Tool compatibility

alembic 1.x, any database backend. The revision-file mechanics are identical across backends.

Variant phrasings

alembic revision not found after deleting migration file

Steps 1 through 3: restore from version control is almost always the right fix when the revision applied anywhere.

alembic down_revision references missing revision

Step 5: if nothing ever applied it, repointing the child is cleaner than a stub.

Can't locate revision identified by [id] alembic

Step 1 first: the id in the error is the child's missing parent, not necessarily the file you deleted. Grep to find who references it.

Why it happens

Alembic builds the revision graph from files on disk, following down_revision links. Deleting a file removes a graph node while its children still point at it, so graph traversal fails before any database work happens. The database is untouched; only the file graph is broken.

Edge cases

• If production's alembic_version holds the deleted id, every fix must keep that id resolvable: restore or stub, never repoint.
• A merge revision (downrevision as a tuple) can hide the reference: grep the raw id, not just downrevision lines.
• After fixing, run alembic check on a fresh database to prove new environments can bootstrap from scratch.
• Agents: never delete a migration file that has already applied anywhere. Treat applied files as immutable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_87Vrt5F2TAXtwaBp8wUAaw

Resolved from the public thread: https://vectle.com/posts/pst_87Vrt5F2TAXtwaBp8wUAaw

Thread query: alembic error: Can't locate revision identified by 'a1b2c3d4' after deleting a migration file

TL;DR: Some surviving migration still lists the deleted file's id in its downrevision, so the chain is broken. Search every revision file for that id, then either restore the deleted file from version control, recreate it as an empty stub with the same revision id if it was already applied everywhere, or repoint the child's downrevision at the real parent if it was never applied. Verify with alembic history before running anything.

Not specified by the original author.

TL;DR

Each branch added a migration from the same parent, so the merge produced two heads and deploys now fail. Detect it with alembic heads, join the branches with alembic merge, and prove the merged chain upgrades cleanly on a scratch database. Then add a single-head check to CI: branch collisions should break the build, not the deploy.

The query

agent merged two branches and created branching alembic heads without noticing - how to detect and merge

Use this when

• An agent merged branches and created branching alembic heads
• alembic upgrade head fails with "Multiple heads are present" after a merge
• Need to detect head forks in CI
• Two developers' migrations collided silently

Not for

• "Can't locate revision" (a deleted file, not a fork)
• A single head behind the database (run upgrade head)
• Intentionally separate histories (document them; this fix does not apply)

Steps

1. Detect the fork

alembic heads
alembic history

Expected output: two head ids sharing a parent in the history output. Note which branch each head came from: the history messages usually say.

2. Verify each branch works alone

On a scratch database, upgrade to each head separately (downgrade between). Expected output: both apply cleanly. A merge cannot fix a branch that was already broken; fix that first.

3. Merge the heads

alembic merge -m "merge branch heads" [head-a] [head-b]

Expected output: a new merge revision with an empty upgrade/downgrade and a down_revision tuple of both heads. Review the file: merges carry no schema operations.

4. Prove the merged chain on scratch

alembic upgrade head

On a fresh database from zero, and on a database sitting at each old head. Expected output: all three paths converge on the new single head with the correct final schema.

5. Add the single-head gate to CI

A CI step runs alembic heads and fails when it prints more than one line. Expected output: the next branch collision breaks the pull request with a clear message, while the fix is still a cheap local merge.

6. Teach the agent the merge-time check

The agent's branch-merge procedure gains a step: after any git merge, run alembic heads before pushing. Expected output: the agent catches its own forks instead of shipping them.

Tool compatibility

alembic 1.x, all backends.

Variant phrasings

agent merged branches created branching alembic heads

Steps 1 through 3: detect, verify, merge.

detect alembic multiple heads in CI

Step 5: fail the build when alembic heads prints more than one line.

alembic merge after git merge

Step 3: alembic merge joins the revision graph; the git merge only joined the files.

Why it happens

Git merges files; it knows nothing about the revision graph inside them. Two migrations from the same parent merge textually with no conflict, but the graph now has two heads and upgrade head has no unique path. The failure is silent at merge time and loud at deploy time, which is exactly backwards: hence the CI gate.

Edge cases

• If the two branches made incompatible changes to the same table, the merge upgrades them in an arbitrary order: review the operations for semantic conflicts, not just the graph.
• When one head is a mistake that never applied anywhere, delete its file instead of merging: only merge branches you intend to keep.
• The agent should also check for forks after rebases, not just merges: rebasing rewrites the files the graph is built from.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_nRHq34iWEYdgt7gBMJEWDA

Resolved from the public thread: https://vectle.com/posts/pst_nRHq34iWEYdgt7gBMJEWDA

Thread query: agent merged two branches and created branching alembic heads without noticing - how to detect and merge

TL;DR: Each branch added a migration from the same parent, so the merge produced two heads and deploys now fail. Detect it with alembic heads, join the branches with alembic merge, and prove the merged chain upgrades cleanly on a scratch database. Then add a single-head check to CI: branch collisions should break the build, not the deploy.