Alembic has refused to autogenerate a migration and printed Target database is not up to date. The message is precise, and once you know what it is comparing it takes about two minutes to resolve. The dangerous part is fixing it the wrong way and losing a revision.
The error comes from one check. When you run alembic revision --autogenerate, Alembic compares the revision (or revisions) recorded in your database against the head of your migration scripts. If they do not match exactly, it aborts before diffing your models, because autogenerating on top of a database that is not fully migrated would produce a migration that silently duplicates or contradicts changes already pending. So it stops. The fix is never to force past the check blindly; it is to work out why the database and the scripts disagree, because there are three distinct causes and they need three different actions.
The examples below assume Alembic 1.13 against PostgreSQL 17, but nothing here is version-specific.
Free · 4 minutes
Is your engineering team shipping safely, or quietly accumulating risk?
Fourteen questions on how work gets from idea to production — cadence, testing, rollback, and the key-person risk in your delivery. Banded finding on screen, full sheet by email.
First, find out where you actually are
Before you change anything, establish the two facts the check is comparing: what revision the database thinks it is on, and what the scripts think head is. Three commands give you all of it.
# What revision does the database record?
alembic current
# What is the head (or heads) of the migration scripts?
alembic heads
# The full lineage, newest first, with branch points marked
alembic history --verbose
The single source of truth on the database side is one small table Alembic maintains, alembic_version. It holds nothing but the revision identifiers the database is stamped at. Read it directly when alembic current surprises you:
-- One row per current head. Usually one row; two means divergence.
SELECT version_num FROM alembic_version;
Now compare. What alembic current prints and what alembic heads prints tell you which of the three situations you are in.
Cause one: the database is genuinely behind
If alembic current shows an older revision than alembic heads, and there is a clean single chain between them in alembic history, the database simply has not had the latest migrations applied. This is the honest case, and there is nothing to fix in Alembic. Apply the outstanding migrations:
alembic upgrade head
Then rerun your autogenerate. If the migrations really were pending, upgrade head runs their op directives, moves alembic_version to head, and the check passes. If upgrade head reports the database is already at head yet the error persists, you are not in this case — you are in one of the next two.
Cause two: the schema is already correct, the record is wrong
This is the case that catches people out. The database schema is right — the columns and tables the latest migration would create already exist — but alembic_version points at an earlier revision. It happens when someone altered the schema by hand, restored from a dump taken at a different revision, or ran a migration’s SQL manually without letting Alembic record it. Running alembic upgrade head here is exactly the wrong move: the migration will try to add a column that already exists and blow up halfway, leaving you in a worse state.
What you want is to correct the bookkeeping without touching the schema. That is what stamp does — it writes a revision into alembic_version and runs none of the migration bodies:
# Only after you have CONFIRMED the live schema already matches this revision.
# stamp updates alembic_version and runs no upgrade/downgrade logic.
alembic stamp head
# Or stamp a specific revision if head is not where the schema actually sits:
alembic stamp 3f9a2b1c8d40
The word "confirmed" is doing real work in that comment. Stamping tells Alembic to trust you that the schema matches the revision. If you stamp head when the schema does not in fact match, you have hidden the drift, not fixed it, and the next autogenerate will produce a migration that assumes a database state you do not have. Inspect the tables first — \d your_table in psql against the migration’s upgrade() body — and only stamp once they agree. This is precisely the kind of change that belongs in a controlled sequence rather than a live console, the same discipline that keeps a PostgreSQL upgrade from turning into an outage.
Cause three: two heads, because two branches diverged
If alembic heads prints two revisions rather than one, the check fails because the database sits on one branch while the scripts have two tips. This is the classic team collision: two developers each generated a migration off the same parent, both merged, and now the history forks. alembic history shows the branch point plainly.
You do not resolve this by deleting one migration. You resolve it with a merge revision, which is an empty migration whose only job is to name both heads as its parents and rejoin them into one:
# Create a merge migration joining every current head.
alembic merge heads -m "merge invoice and audit branches"
# Or name the two revisions explicitly:
alembic merge -m "merge branches" 3f9a2b1c8d40 a71e0c94b2ff
# Then bring the database up to the new single head.
alembic upgrade head
The generated merge file has empty upgrade() and downgrade() functions, and that is correct — it changes no schema, it only reunites the lineage. After it, alembic heads returns a single revision and autogenerate works again. Commit the merge migration like any other; it is part of the history now.
The rule that stops it recurring
All three causes share one root: the database’s recorded revision and the migration scripts drifted apart, and someone reached for --autogenerate before checking. The habit that prevents it is cheap — run alembic current and alembic heads before you generate anything, and never let a hand-edit to the schema happen without a matching migration or a deliberate stamp. Divergent heads in particular are a merge-hygiene problem, not an Alembic problem, and they are worth a continuous check that fails the build the moment alembic heads returns more than one line. A migration history is a contract about the shape of your data, and like any contract worth keeping, it is cheaper to protect than to reconstruct.
Force past the check and you are guessing at your own schema. Read alembic_version, decide which of the three cases you are in, and the fix is unambiguous.
Free interactive tool
Website compliance checklist
What your site has to do, based on what it actually does
Answer as much or as little as you like — the list builds as you go. Nothing is stored against your name and no email is required.
Everything that applies
Ordered by what to do first: legal requirements you can close quickly, then larger pieces of work, then what is expected rather than required. Not exhaustive, and not a legal audit.
Dated PDF, yours to keep or circulate.
Most technology problems are not technology problems. They are control problems.
The systems exist. The investment has been made. The question is whether leadership can understand, direct, evidence, and sustain what those systems produce. Find out where control exists — and where it only appears to.