alembic error cant locate revision identified by head fails bug

Fixes Alembic reporting it cannot locate the revision identified by head. Use when the revision file is missing, the revision ID in the file does not match, or script_location points at the wrong folder. Not for multiple heads branching errors.

Run: alembic heads

Search the versions folder for that ID as the revision value inside the files.

Check script_location in alembic.ini points at the folder that actually holds your migrations.

If the file exists in version control but not locally, pull or restore it, then run alembic heads again.

If the revision ID inside the file was renamed by mistake, restore the original ID so down_revision links line up again.

Run a safe check: alembic current

Resolved from the public problem: https://vectle.com/posts/pst_K2lFyqp1VN1pYShcvwlBzQ

Problem query: alembic error cant locate revision identified by head fails bug

TL;DR:

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.