{"id":"ce917bf9b0935879","repo":"sqlalchemy/alembic","slug":"this-migrationscript-instance-has-a-multiple-entry","errorCode":null,"errorMessage":"This MigrationScript instance has a multiple-entry list for UpgradeOps; please use the upgrade_ops_list attribute.","messagePattern":"This MigrationScript instance has a multiple-entry list for UpgradeOps; please use the upgrade_ops_list attribute\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"alembic/operations/ops.py","lineNumber":2831,"sourceCode":"        self.splice = splice\n        self.branch_label = branch_label\n        self.version_path = (\n            pathlib.Path(version_path).as_posix() if version_path else None\n        )\n        self.depends_on = depends_on\n        self.upgrade_ops = upgrade_ops\n        self.downgrade_ops = downgrade_ops\n\n    @property\n    def upgrade_ops(self) -> UpgradeOps | None:\n        \"\"\"An instance of :class:`.UpgradeOps`.\n\n        .. seealso::\n\n            :attr:`.MigrationScript.upgrade_ops_list`\n        \"\"\"\n        if len(self._upgrade_ops) > 1:\n            raise ValueError(\n                \"This MigrationScript instance has a multiple-entry \"\n                \"list for UpgradeOps; please use the \"\n                \"upgrade_ops_list attribute.\"\n            )\n        elif not self._upgrade_ops:\n            return None\n        else:\n            return self._upgrade_ops[0]\n\n    @upgrade_ops.setter\n    def upgrade_ops(self, upgrade_ops: UpgradeOps | list[UpgradeOps]) -> None:\n        self._upgrade_ops = util.to_list(upgrade_ops)\n        for elem in self._upgrade_ops:\n            assert isinstance(elem, UpgradeOps)\n\n    @property\n    def downgrade_ops(self) -> DowngradeOps | None:\n        \"\"\"An instance of :class:`.DowngradeOps`.","sourceCodeStart":2813,"sourceCodeEnd":2849,"githubUrl":"https://github.com/sqlalchemy/alembic/blob/44fb3450330204b222ff05135e1fbbbdb28c44db/alembic/operations/ops.py#L2813-L2849","documentation":"Raised by the MigrationScript.upgrade_ops property when more than one UpgradeOps entry exists in the internal _upgrade_ops list. The scalar property can only return a single entry; once multiple upgrade op streams exist (multi-pass autogenerate, process_revision_directives producing several UpgradeOps) you must read upgrade_ops_list instead.","triggerScenarios":"Accessing script.upgrade_ops on a MigrationScript whose __init__ was passed a list of multiple UpgradeOps, or whose setter received a list; typically inside custom process_revision_directives hooks that append multiple UpgradeOps, or when rendering a revision that performs several independent upgrade passes.","commonSituations":"Custom autogenerate process_revision_directives that splits work into multiple UpgradeOps; iterating autogenerated scripts and accessing the scalar property instead of the list property.","solutions":["Switch to script.upgrade_ops_list and iterate over all entries instead of script.upgrade_ops.","If you only need the single-entry case, ensure exactly one UpgradeOps is stored before accessing the scalar property.","In rendering/process_revision_directives code, branch on len(upgrade_ops_list) > 1 and use the list form."],"exampleFix":"// before\nscript = scripts[0]\nops = script.upgrade_ops  # raises ValueError when multiple\n\n// after\nscript = scripts[0]\nfor ops in script.upgrade_ops_list:\n    ...","handlingStrategy":"type-guard","validationCode":"def get_upgrade_ops(script):\n    n = len(script.upgrade_ops_list)\n    if n > 1:\n        return script.upgrade_ops_list  # multi-entry\n    return script.upgrade_ops_list[0] if n == 1 else None","typeGuard":"def has_multiple_upgrade_ops(script) -> bool:\n    return len(script.upgrade_ops_list) > 1","tryCatchPattern":"try:\n    ops = script.upgrade_ops\nexcept ValueError:\n    ops = script.upgrade_ops_list","preventionTips":["Prefer the upgrade_ops_list accessor in generic/render code.","Branch on len(upgrade_ops_list) in process_revision_directives hooks.","Document that scalar access is single-entry only."],"tags":["alembic","autogenerate","migrations","internals"],"analyzedSha":"44fb3450330204b222ff05135e1fbbbdb28c44db","analyzedAt":"2026-08-04T19:57:10.248Z","schemaVersion":2}