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

Alembic reads the current revision id from the alembic_version table and looks for a matching script in the versions directory. When that script is missing (a deleted or branch-only migration), it fails with "Can't locate revision".

What this error means

alembic upgrade head or alembic current fails with "Can't locate revision identified by 'abc123'" because the recorded revision has no matching file.

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

Common causes

The database references a revision not on this branch

The alembic_version table holds an id created on another branch or since deleted, so the matching script is absent in this checkout.

A migration file was removed without downgrading

A versions file was deleted while the database still records that revision as current.

How to fix it

Run against a clean database in CI

Start from an empty database so alembic_version only ever references revisions present on this branch.

alembic upgrade head

Reconcile the recorded revision

1. Inspect the id in alembic_version and find which branch created it.
2. Restore the missing migration file, or stamp the database to a known present revision in a disposable environment.
3. Avoid deleting migrations that any database still records.

alembic stamp head

How to prevent it

• Migrate fresh databases in CI so the version table stays consistent.
• Do not delete migration files that databases still reference.
• Keep one linear, shared migration history across branches.

Related guides