Alembic "Multiple head revisions are present" in CI

By Kaveh Alemi·Latchkey

Alembic migrations form a tree. When two branches each create a revision with the same parent (down_revision), there are two heads, and upgrade head cannot pick one. Alembic asks you to merge them.

What this error means

alembic upgrade head fails with "Multiple head revisions are present for given argument 'head'; please specify a specific target revision" after two branches added migrations.

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 added migrations off the same parent

Each feature branch created a revision whose down_revision is the same, so merging them yields two heads.

Parallel work without rebasing the migration chain

Migrations were authored independently and not re-parented before merge, producing a fork in the revision tree.

How to fix it

Create a merge revision

Generate a migration that joins the two heads into one so upgrade head is unambiguous again.

alembic merge -m "merge heads" heads
alembic upgrade head

Or re-parent one migration

1. Pick which migration should come second.
2. Set its down_revision to the other branch's head so the chain is linear.
3. Run alembic upgrade head to confirm a single head.

How to prevent it

• Detect multiple heads in CI with alembic heads and fail if more than one.
• Re-parent or merge migrations when branches both add them.
• Keep a linear revision chain on the main branch.

Frequently asked questions

Related guides

References

• GitHub Actions documentation