What causes "No such revision or branch '%s'%s" in sqlalchemy/alembic?

Run 'alembic history' or script.walk_revisions() to confirm the exact revision id.

sqlalchemy/alembic · error · ResolutionError

No such revision or branch '%s'%s

Error message

No such revision or branch '%s'%s

What it means

Raised by _revision_for_ident when a (possibly partial) identifier matches zero revisions in the map. Partial identifiers must be at least 4 characters long; the message appends a hint about this when the input is shorter. It is a ResolutionError.

Source

Thrown at alembic/script/revision.py:630

        try:
            revision = self._revision_map[resolved_id]
        except KeyError:
            # break out to avoid misleading py3k stack traces
            revision = False
        revs: Sequence[str]
        if revision is False:
            assert resolved_id
            # do a partial lookup
            revs = [
                x
                for x in self._revision_map
                if x and len(x) > 3 and x.startswith(resolved_id)
            ]

            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,

View on GitHub (pinned to 44fb345033)

Solutions

Run 'alembic history' or script.walk_revisions() to confirm the exact revision id.
If using a partial prefix, supply at least 4 characters and ensure it is unique.
If a migration was deleted, restore it or fix the down_revision/depends_on pointers that reference it.
Make sure the script directory location (script_location config) points at the right folder.

Example fix

# before
alembic downgrade abc          # < 4 chars, no match
# after
alembic downgrade abc12345def  # full or >=4-char unique prefix

Defensive patterns

Strategy: validation

Validate before calling

all_ids = {r.revision for r in script.walk_revisions()}
if target not in all_ids and not any(
    rid.startswith(target) for rid in all_ids if len(target) >= 4
):
    raise ValueError('unknown revision: %s' % target)

Try / catch

from alembic.script.revision import ResolutionError
try:
    rev = script.get_revision(target)
except ResolutionError as e:
    # unknown/ambiguous id; log and fall back
    ...

Prevention

Always pass full revision ids in automation.
If using prefixes, ensure >= 4 characters and uniqueness.
Validate ids against the script directory before issuing commands.

When it happens

Trigger: Passing a revision id that does not exist; a partial prefix shorter than 4 chars; a partial prefix of >= 4 chars that no revision starts with; a down_revision pointing at a deleted migration.

Common situations: Referencing a revision that was renamed or removed; stale cookie/cached revision id in a deploy tool; checkout mismatch where the migration file exists in one branch but not the current one; typo in a downgrade target.

Related errors

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