{"id":"bd7f0fbcad63fbdc","repo":"sqlalchemy/alembic","slug":"ambiguous-upgrade-from-multiple-current-revisions","errorCode":null,"errorMessage":"Ambiguous upgrade from multiple current revisions","messagePattern":"Ambiguous upgrade from multiple current revisions","errorType":"exception","errorClass":"RevisionError","httpStatus":null,"severity":"error","filePath":"alembic/script/revision.py","lineNumber":1269,"sourceCode":"                            ),\n                            branch_label,\n                        )\n                        # Find the tips of this set of revisions (revisions\n                        # without children within the set).\n                        start_revs = tuple(\n                            {rev.revision for rev in active_on_branch}\n                            - {\n                                down\n                                for rev in active_on_branch\n                                for down in rev._normalized_down_revisions\n                            }\n                        )\n                        if not start_revs:\n                            # We must need to go right back to base to find\n                            # a starting point for this branch.\n                            start_revs = (None,)\n                if len(start_revs) > 1:\n                    raise RevisionError(\n                        \"Ambiguous upgrade from multiple current revisions\"\n                    )\n                # Walk up from unique target revision.\n                rev = self._walk(\n                    start=start_revs[0],\n                    steps=relative,\n                    branch_label=branch_label,\n                    no_overwalk=assert_relative_length,\n                )\n                if rev is None:\n                    raise RevisionError(\n                        \"Relative revision %s didn't \"\n                        \"produce %d migrations\" % (relative_str, abs(relative))\n                    )\n                return (rev,)\n            else:\n                # Walk is relative to a given revision, not the current state.\n                return (","sourceCodeStart":1251,"sourceCodeEnd":1287,"githubUrl":"https://github.com/sqlalchemy/alembic/blob/44fb3450330204b222ff05135e1fbbbdb28c44db/alembic/script/revision.py#L1251-L1287","documentation":"Raised by _parse_upgrade_target for a relative upgrade ('+n', no explicit symbol) when the current revisions resolve to more than one starting point that cannot be disambiguated by a branch label. Relative upgrades require a single unambiguous starting revision; multiple current heads make 'current + n' undefined. It is a RevisionError.","triggerScenarios":"Running 'alembic upgrade +2' on a database stamped with multiple heads (multi-branch tree) without specifying a branch.","commonSituations":"Multi-head database state (e.g., after merging branches at the script level but the DB still holds several heads); relative upgrades in CI against a branched tree.","solutions":["Merge the heads with 'alembic merge' so the database has a single head.","Scope the upgrade with a branch label: 'alembic upgrade mybranch@+2'.","Upgrade to an absolute target revision instead of a relative offset."],"exampleFix":"# before\nalembic upgrade +2   # multiple current heads -> ambiguous\n# after\nalembic upgrade mybranch@+2   # or merge heads first","handlingStrategy":"validation","validationCode":"with engine.begin() as conn:\n    ctx = MigrationContext.configure(conn)\n    current = ctx.get_current_revisions()  # tuple\nif len(set(current)) > 1:\n    raise ValueError(\n        'relative upgrade ambiguous from heads: %s; scope a branch' % (current,)\n    )","typeGuard":null,"tryCatchPattern":"from alembic.script.revision import RevisionError\ntry:\n    command.upgrade(cfg, '+%d' % steps)\nexcept RevisionError as e:\n    if 'Ambiguous upgrade' in str(e):\n        command.upgrade(cfg, '%s@+%d' % (branch, steps))  # scope a branch","preventionTips":["Merge heads before issuing relative upgrades.","Scope relative upgrades with a branch label in branched trees.","Use absolute upgrade targets in deployment automation."],"tags":["relative-revision","upgrade","ambiguous","multiple-heads","alembic"],"analyzedSha":"44fb3450330204b222ff05135e1fbbbdb28c44db","analyzedAt":"2026-08-04T19:57:10.248Z","schemaVersion":2}