FastAPI Alembic "Target database is not up to date" in CI

Alembic compares the database revision against your migration heads. On a fresh CI database no migrations have run, so it is not up to date, and after a bad merge you can have multiple heads Alembic refuses to auto-resolve.

What this error means

A migration or autogenerate step fails with "Target database is not up to date" or "Multiple head revisions are present ...; please specify a specific target revision".

python

FAILED: Target database is not up to date.

# or, after a merge:
alembic.util.exc.CommandError: Multiple head revisions are present for given
argument 'head'; please specify a specific target revision

Common causes

Migrations were not applied to the test database

CI created a fresh database but never ran alembic upgrade head, so its revision is empty and out of date.

Two migration heads after a branch merge

Parallel branches each added a migration; merging left two heads that Alembic will not pick between automatically.

How to fix it

Upgrade the database in CI before tests

Run the migrations against the test database so its revision matches head.

Terminal

alembic upgrade head

Merge the divergent heads

Create a merge revision so there is a single head, then commit it.