What causes "Multiple revisions start with '%s': %s..." in sqlalchemy/alembic?

Provide more characters of the revision id until it is unique (ideally the full id).

sqlalchemy/alembic · error · ResolutionError

Multiple revisions start with '%s': %s...

Error message

Multiple revisions start with '%s': %s...

What it means

Raised by _revision_for_ident when a partial identifier (>= 4 characters) matches more than one revision, making the target ambiguous. The message lists the first three matching ids. It is a ResolutionError.

Source

Thrown at alembic/script/revision.py:644

            if branch_rev:
                revs = self.filter_for_lineage(revs, check_branch)
            if not revs:
                raise ResolutionError(
                    "No such revision or branch '%s'%s"
                    % (
                        resolved_id,
                        (
                            "; please ensure at least four characters are "
                            "present for partial revision identifier matches"
                            if len(resolved_id) < 4
                            else ""
                        ),
                    ),
                    resolved_id,
                )
            elif len(revs) > 1:
                raise ResolutionError(
                    "Multiple revisions start "
                    "with '%s': %s..."
                    % (resolved_id, ", ".join("'%s'" % r for r in revs[0:3])),
                    resolved_id,
                )
            else:
                revision = self._revision_map[revs[0]]

        if check_branch and revision is not None:
            assert branch_rev is not None
            assert resolved_id
            if not self._shares_lineage(
                revision.revision, branch_rev.revision
            ):
                raise ResolutionError(
                    "Revision %s is not a member of branch '%s'"
                    % (revision.revision, check_branch),
                    resolved_id,

View on GitHub (pinned to 44fb345033)

Solutions

Provide more characters of the revision id until it is unique (ideally the full id).
Use the symbolic 'head'/'base' or a branch label if appropriate.
Regenerate colliding revision ids with 'alembic revision' if the collision is on a real prefix.

Example fix

# before
alembic upgrade abcd   # matches abcd111..., abcd222...
# after
alembic upgrade abcd111abcdef

Defensive patterns

Strategy: validation

Validate before calling

matches = [
    rid for rid in {r.revision for r in script.walk_revisions()}
    if rid.startswith(prefix)
]
if len(matches) > 1:
    raise ValueError('ambiguous prefix %s: %s' % (prefix, matches))

Try / catch

from alembic.script.revision import ResolutionError
try:
    rev = script.get_revision(prefix)
except ResolutionError as e:
    if 'Multiple revisions' in str(e):
        # lengthen the prefix until unique
        ...

Prevention

Use full revision ids whenever possible.
Never hardcode short prefixes in scripts.
Check uniqueness of a prefix before using it.

When it happens

Trigger: Passing a prefix like 'abc1' that two or more revision ids share (revision ids are random but collisions on a short prefix are possible); committing migrations whose ids share a common stem.

Common situations: Short revision-id prefixes in automation scripts; tooling that truncates ids for display and then feeds the truncated form back into commands.

Related errors

AI-assisted analysis of sqlalchemy/alembic@44fb345033 (2026-08-04). Data as JSON: /data/errors/d5ea6d34176db533.json. Report an issue: GitHub.