sqlalchemy/alembic · error · RevisionError

Requested revision %s overlaps with other requested revision

Error message

Requested revision %s overlaps with other requested revisions %s

What it means

Raised inside _iterate_related_revisions when called with check=True and the set of target revisions overlap each other in the traversal (one target is an ancestor/dependent of another within the same requested set). This guards against asking for revisions whose lineages are not independent. It is a RevisionError.

Source

Thrown at alembic/script/revision.py:910

                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),
                        )
                    )

    def _topological_sort(
        self,
        revisions: Collection[Revision],
        heads: Any,
    ) -> list[str]:
        """Yield revision ids of a collection of Revision objects in
        topological sorted order (i.e. revisions always come after their
        down_revisions and dependencies). Uses the order of keys in
        _revision_map to sort.

View on GitHub (pinned to 44fb345033)

Solutions

1. Dedupe and de-overlap the requested revision set before calling the API (remove targets that are ancestors/dependents of others).
2. Prefer the high-level iterate_revisions()/upgrade/downgrade path rather than internal traversal helpers.
3. If hit via normal commands, check for duplicate or cross-dependent revision ids in your request.

# dedupe and de-overlap a requested target set
targets = list(dict.fromkeys(targets))  # unique, order preserved
# if you traverse ancestors/dependents, drop targets already covered
...

from alembic.script.revision import RevisionError
try:
    ...  # call passing the target set
except RevisionError as e:
    if 'overlaps' in str(e):
        # remove overlapping targets and retry
        ...

When it happens

Trigger: Calling internal APIs that pass overlapping revision sets with the check flag (e.g., certain _shares_lineage / _get_descendant_nodes paths used during upgrade/downgrade planning); requesting two targets where one depends on the other.

Common situations: Custom migration planners that pass overlapping revision sets; rarely surfaced from standard CLI usage.

Related errors

• Dependency resolution failed; broken map
• 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/2f501a41c005ecd5.json. Report an issue: GitHub.