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

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

What this error means

alembic upgrade head fails immediately, naming a revision id it cannot locate. The referenced file is genuinely absent from the checked-out tree.

psql

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

Common causes

Migration file missing from the checkout

The recorded revision's file was never committed, was deleted, or lives on an unmerged branch.

Database ahead of the code

A shared database was stamped at a newer revision than this branch provides, so the id has no script here.

Divergent branch history

Two branches created different revisions; one branch's ids are unresolvable against the other's versions/.

How to fix it

Restore or merge the missing revision

Bring the referenced script back, usually by merging the branch that holds it.

Terminal

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

Use a clean database in CI

Start each run from an empty database so alembic_version builds fresh.
Run alembic upgrade head against that clean database.
Avoid pointing CI at a shared database stamped by other branches.

How to prevent it

Commit every generated revision; never delete an applied one.
Run migrations against an ephemeral database in CI.
This is deterministic - retrying without restoring the file fails identically.