{"id":"fd776cda8d4d4a9b","repo":"sqlalchemy/alembic","slug":"multiple-heads-are-present-for-given-argument-s","errorCode":null,"errorMessage":"Multiple heads are present for given argument '%s'; %s","messagePattern":"Multiple heads are present for given argument '(.+?)'; (.+?)","errorType":"exception","errorClass":"MultipleHeads","httpStatus":null,"severity":"error","filePath":"alembic/script/revision.py","lineNumber":501,"sourceCode":"        preferred.\n\n        :param branch_label: optional branch name which will limit the\n         heads considered to those which include that branch_label.\n\n        :return: a string revision number.\n\n        .. seealso::\n\n            :meth:`.ScriptDirectory.get_heads`\n\n        \"\"\"\n        current_heads: Sequence[str] = self.heads\n        if branch_label:\n            current_heads = self.filter_for_lineage(\n                current_heads, branch_label\n            )\n        if len(current_heads) > 1:\n            raise MultipleHeads(\n                current_heads,\n                \"%s@head\" % branch_label if branch_label else \"head\",\n            )\n\n        if current_heads:\n            return current_heads[0]\n        else:\n            return None\n\n    def _get_base_revisions(self, identifier: str) -> tuple[str, ...]:\n        return self.filter_for_lineage(self.bases, identifier)\n\n    def get_revisions(\n        self, id_: _GetRevArg | None\n    ) -> tuple[_RevisionOrBase | None, ...]:\n        \"\"\"Return the :class:`.Revision` instances with the given rev id\n        or identifiers.\n","sourceCodeStart":483,"sourceCodeEnd":519,"githubUrl":"https://github.com/sqlalchemy/alembic/blob/44fb3450330204b222ff05135e1fbbbdb28c44db/alembic/script/revision.py#L483-L519","documentation":"Raised by get_current_head(branch_label) when more than one head revision exists for the requested scope (the whole tree, or a branch_label). get_current_head is only valid when there is exactly one head; the docstring explicitly directs callers to ScriptDirectory.get_heads() when branching is possible. It is a MultipleHeads exception (subclass of RevisionError).","triggerScenarios":"Calling get_current_head() (no args) on a script directory that has diverged into multiple heads, or get_current_head('mybranch') where that branch lineage still has more than one head. Common via 'alembic upgrade head' or programmatic command.runs() when the repo has unresolved branches.","commonSituations":"Two developers added migrations off the same parent and merged them, creating two heads; a feature-branch migration with branch_labels that was never merged; CI running 'alembic upgrade head' on a multi-head tree.","solutions":["Run 'alembic heads' to list all heads, then 'alembic merge -m \"merge heads\" <head1> <head2>' to create a merge revision.","Use get_heads() (plural) in code instead of get_current_head() to handle branching explicitly.","Specify an explicit target revision id instead of the symbolic 'head' when upgrading."],"exampleFix":"// before\nhead = script.get_current_head()  # MultipleHeads\n// after\nheads = script.get_heads()\nif len(heads) == 1:\n    head = heads[0]\nelse:\n    # merge or pick an explicit target\n    raise SystemExit(\"multiple heads: %s\" % heads)","handlingStrategy":"try-catch","validationCode":"from alembic.script.revision import MultipleHeads\nheads = script.get_heads()\nif len(heads) > 1:\n    # merge or disambiguate before calling get_current_head\n    ...","typeGuard":null,"tryCatchPattern":"from alembic.script.revision import MultipleHeads\ntry:\n    head = script.get_current_head(branch)\nexcept MultipleHeads as e:\n    # e.heads lists the heads; merge or pick one explicitly\n    head = e.heads[0]  # or run alembic.merge","preventionTips":["Use get_heads() (plural) whenever branching is possible.","Merge feature branches with 'alembic merge' before deploy.","Pin explicit revision ids in automation instead of 'head'."],"tags":["multiple-heads","branching","alembic"],"analyzedSha":"44fb3450330204b222ff05135e1fbbbdb28c44db","analyzedAt":"2026-08-04T19:57:10.248Z","schemaVersion":2}