{"id":"8b8dccf77236f9df","repo":"sqlalchemy/alembic","slug":"branch-name-s-in-revision-s-already-used-by-re","errorCode":null,"errorMessage":"Branch name '%s' in revision %s already used by revision %s","messagePattern":"Branch name '(.+?)' in revision (.+?) already used by revision (.+?)","errorType":"exception","errorClass":"RevisionError","httpStatus":null,"severity":"error","filePath":"alembic/script/revision.py","lineNumber":324,"sourceCode":"                _real_bases,\n                map_=cast(_RevisionMapType, rev_map),\n            )\n        )\n        deleted_revs = set(rev_map.keys()) - total_space\n        if deleted_revs:\n            raise DependencyCycleDetected(sorted(deleted_revs))\n\n    def _map_branch_labels(\n        self, revisions: Collection[Revision], map_: _RevisionMapType\n    ) -> None:\n        for revision in revisions:\n            if revision.branch_labels:\n                assert revision._orig_branch_labels is not None\n                for branch_label in revision._orig_branch_labels:\n                    if branch_label in map_:\n                        map_rev = map_[branch_label]\n                        assert map_rev is not None\n                        raise RevisionError(\n                            \"Branch name '%s' in revision %s already \"\n                            \"used by revision %s\"\n                            % (\n                                branch_label,\n                                revision.revision,\n                                map_rev.revision,\n                            )\n                        )\n                    map_[branch_label] = revision\n\n    def _add_branches(\n        self, revisions: Collection[Revision], map_: _RevisionMapType\n    ) -> None:\n        for revision in revisions:\n            if revision.branch_labels:\n                revision.branch_labels.update(revision.branch_labels)\n                for node in self._get_descendant_nodes(\n                    [revision], map_, include_dependencies=False","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/sqlalchemy/alembic/blob/44fb3450330204b222ff05135e1fbbbdb28c44db/alembic/script/revision.py#L306-L342","documentation":"Raised as RevisionError in _map_branch_labels() when a branch_label declared on a revision collides with a name already present in the revision map (i.e. another revision id or an already-mapped branch label). Branch labels are used to address revision branches and must be unique identifiers within the revision namespace; a collision makes branch addressing ambiguous.","triggerScenarios":"Two revisions both declaring the same branch_label; a branch_label that equals an existing revision identifier; declaring a branch_label on a revision that another revision already claimed as its branch_label.","commonSituations":"Setting identical branch_labels on parallel branches; naming a branch label the same as a revision hash; copy-pasting a revision file and forgetting to change the branch_label; using --branch-label with a name that's already taken.","solutions":["Give each branch a unique branch_label distinct from all revision ids and other labels.","Remove the duplicate branch_label from one of the conflicting revisions.","Re-create the revision with 'alembic revision --branch-label <unique_name>'."],"exampleFix":"// before\n# revision aaa branch_labels=('feature',)\n# revision bbb branch_labels=('feature',)  # collision -> RevisionError\n\n// after\n# revision bbb branch_labels=('feature2',)","handlingStrategy":"validation","validationCode":"def branch_labels_unique(revisions):\n    seen = {}\n    for rev in revisions:\n        for label in (getattr(rev, 'branch_labels', None) or ()):\n            if label in seen:\n                return False, (label, seen[label], rev.revision)\n            seen[label] = rev.revision\n    return True, None","typeGuard":null,"tryCatchPattern":"try:\n    script_dir.get_revision(branch_label)\nexcept Exception as e:\n    if 'already used by revision' in str(e):\n        # rename/remove the duplicate branch_label on the conflicting revision\n        ...\n    else:\n        raise","preventionTips":["Use unique branch labels distinct from all revision ids.","Don't reuse branch labels across parallel branches.","Generate revisions with 'alembic revision --branch-label <unique>'."],"tags":["alembic","revisions","branch-labels","migration-graph","configuration"],"analyzedSha":"44fb3450330204b222ff05135e1fbbbdb28c44db","analyzedAt":"2026-08-04T19:57:10.248Z","schemaVersion":2}