Alembic "Can't locate revision identified by ... (down_revision)" in CI

Alembic builds the migration graph from the files in versions/. A revision referenced as a down_revision (or recorded in alembic_version) is missing, so Alembic cannot order the chain and stops.

What this error means

An alembic upgrade head step fails with "alembic.util.exc.CommandError: Can't locate revision identified by 'a1b2c3d4'."

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

Common causes

A migration file is missing from versions/

A branch added a revision that another branch deleted or never merged, so a down_revision points at a hash with no file present.

The database records an unknown revision

The alembic_version table holds a hash that no longer exists in the checked-out migrations, leaving the chain broken.

How to fix it

Restore the missing revision or fix the chain

1. List heads and history to see where the chain breaks.
2. Restore the missing migration file, or correct the down_revision of the orphaned one.
3. Re-run the upgrade once the graph is contiguous.

alembic history --verbose
alembic heads

Start the test DB from an empty schema

Run migrations against a fresh database in CI so a stale alembic_version from a previous run cannot reference a missing revision.

alembic upgrade head  # against a clean service DB

How to prevent it

• Commit every referenced migration file, never just the down_revision.
• Run migrations against a clean database in CI.
• Resolve branched migration heads before merging.

Related guides