Alembic "Can't locate revision identified by" in CI

By Daniel Zoghalchali·Latchkey

Alembic read the current revision recorded in alembic_version (or a down_revision reference) and could not find a matching script in the versions/ directory. The history graph has a dangling pointer.

What this error means

alembic upgrade head (or current/history) fails immediately, naming a revision id it cannot locate. It is deterministic - the referenced file is genuinely absent from the checked-out tree.

alembic output

alembic.util.exc.CommandError: Can't locate revision identified by 'a1b2c3d4e5f6'

Common causes

Migration file missing from the checkout

The alembic_version table (or another script’s down_revision) references a revision whose file was never committed, was deleted, or lives on an unmerged branch.

Database ahead of the code

The target database was stamped at a newer revision than the branch under test provides, so the recorded id has no script here.

Branch with divergent history

Two branches created different revisions; checking out one leaves the other’s ids unresolvable against this versions/ folder.

How to fix it

Restore or merge the missing revision

Bring the referenced script back into versions/ - usually by merging the branch that contains it.

Terminal

alembic history --verbose      # see the expected chain
git log -- migrations/versions  # find the commit that holds the missing file

Re-stamp the database to a known revision

If the database was stamped at a revision the code no longer has and that is intended, stamp it to a revision that exists, then upgrade.

Terminal

alembic stamp <existing_revision>
alembic upgrade head

Use a clean database for CI

Start each CI run from an empty database so alembic_version is built fresh.
Run alembic upgrade head against that clean database to apply the full chain.
Avoid pointing CI at a shared database stamped by other branches.

How to prevent it

Commit every generated revision file; never delete one that has been applied.
Run migrations against an ephemeral database in CI.
Merge migration branches deliberately to keep the revision graph connected.

Frequently asked questions

What causes ""Can't locate revision identified by""?

The alembic_version table (or another script’s down_revision) references a revision whose file was never committed, was deleted, or lives on an unmerged branch.

How do I fix "Can't locate revision identified by"?

Bring the referenced script back into versions/ - usually by merging the branch that contains it.

References

GitHub Actions documentation