Alembic "Multiple head revisions are present" in CI

Two migrations share the same down_revision, creating a fork in the history graph with more than one head. Alembic cannot upgrade to a single "head" until the branches are merged.

What this error means

alembic upgrade head fails because "head" is ambiguous, or a check reports multiple heads. It typically appears after two branches each added a revision off the same parent and both were merged into the codebase.

alembic output

alembic.util.exc.CommandError: Multiple head revisions are present
for given argument 'head'; please specify a specific target
revision, '<branchname>@head' to narrow to a specific head,
or 'heads' for all heads

Common causes

Two branches forked the same parent

Each feature branch generated a revision with the same down_revision. Merging both branches leaves two leaf nodes - two heads - in the graph.

No merge revision created

A fork is legitimate, but Alembic needs an explicit merge revision to rejoin the branches into a single head.

How to fix it

Create a merge revision

Generate a revision that has both heads as parents, rejoining the graph.

Terminal

alembic heads                 # list the two head ids
alembic merge -m "merge heads" <head1> <head2>
alembic upgrade head

Or rebase one branch onto the other

Pick one branch’s revision and set its down_revision to the other branch’s head.
This linearizes history into a single chain with one head.
Prefer a merge revision when both branches are already shared.

How to prevent it

Add a CI check that there is exactly one head (alembic heads | wc -l).
Rebase or merge migration branches before merging feature branches.
Coordinate revision creation so two branches don’t fork the same parent unnoticed.