sqlalchemy/alembic · error · RevisionError

Dependency resolution failed; broken map

Error message

Dependency resolution failed; broken map

What it means

Raised inside _iterate_related_revisions when a dependency pointer in the map resolves to a Revision object whose own .revision attribute disagrees with the key it was looked up by. This is an internal integrity check indicating the revision map is corrupted/inconsistent (e.g., two ids aliasing one object). It is a RevisionError and should not normally be reachable by user input.

Source

Thrown at alembic/script/revision.py:900

            target = is_revision(target_for)
            todo.append(target)
            if check:
                per_target = set()

            while todo:
                rev = todo.pop()
                if check:
                    per_target.add(rev)

                if rev in seen:
                    continue
                seen.add(rev)
                # Check for map errors before collecting.
                for rev_id in fn(rev):
                    next_rev = map_[rev_id]
                    assert next_rev is not None
                    if next_rev.revision != rev_id:
                        raise RevisionError(
                            "Dependency resolution failed; broken map"
                        )
                    todo.append(next_rev)
                yield rev
            if check:
                overlaps = per_target.intersection(targets).difference(
                    [target]
                )
                if overlaps:
                    raise RevisionError(
                        "Requested revision %s overlaps with "
                        "other requested revisions %s"
                        % (
                            target.revision,
                            ", ".join(r.revision for r in overlaps),
                        )
                    )

View on GitHub (pinned to 44fb345033)

Solutions

1. Report as a bug to alembic if produced with stock scripts and unmodified Revision objects.
2. Audit any custom code that constructs or mutates Revision objects / the revision map directly.
3. Rebuild the map from scratch via the script directory generator instead of mutating it.

from alembic.script.revision import RevisionError
try:
    list(rev_map.iterate_revisions(upper, lower))
except RevisionError as e:
    if 'broken map' in str(e):
        # rebuild the map from the script directory; report as bug
        ...

When it happens

Trigger: Corrupted or hand-built revision map where map_[rev_id].revision != rev_id; bugs in add_revision / _add_depends_on that mis-index a Revision; monkeypatching of Revision.revision after insertion.

Common situations: Test fixtures that build a map by hand and reuse the same Revision object under multiple keys; plugin code that mutates Revision.revision in place; very rare alembic internal bugs.

Related errors

• Requested revision %s overlaps with other requested revision
• revision %s not in map
• Can't send params and multiparams at the same time
• Can't drop table in batch mode
• Constraint must have a name

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