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

By Kaveh Alemi·Latchkey

Alembic found revisions in versions/ that are newer than the database’s current revision. Commands like revision --autogenerate refuse to run against a database that is behind head.

What this error means

alembic revision --autogenerate (or a check command) aborts with "Target database is not up to date", listing the current vs head revision. It happens when migrations exist but were not applied first.

FAILED: Target database is not up to date.
Current revision(s) for postgresql://...: 9f8e7d6c5b4a
Head(s): a1b2c3d4e5f6

Common causes

Database behind the migration head

New revision files were added but alembic upgrade head was not run, so the database’s current revision lags the latest script.

Autogenerate run before upgrading

Autogenerate compares models to the database and requires it to be at head first; running it on a behind database is rejected to avoid a corrupt diff.

How to fix it

Upgrade to head before the guarded command

Apply all pending migrations, then run autogenerate or the check.

alembic upgrade head
alembic revision --autogenerate -m "add orders status"

Verify current vs head

1. Run alembic current and alembic heads to see the gap.
2. Apply the difference with alembic upgrade head.
3. In CI, always upgrade first so the database is at head before any diff or check.

How to prevent it

• Run alembic upgrade head as the first migration step in CI.
• Never autogenerate against a database that is behind head.
• Add a CI check that the database matches head after upgrading.

Frequently asked questions

Related guides

References

• GitHub Actions documentation