{"record":{"id":"79092aae029ca24a","repo":"Lightning-AI/pytorch-lightning","slug":"to-use-fn-name-please-disable-automatic-optimiz","errorCode":null,"errorMessage":"to use {fn_name}, please disable automatic optimization: set model property `automatic_optimization` as False","messagePattern":"to use (.+?), please disable automatic optimization: set model property `automatic_optimization` as False","errorType":"exception","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/core/module.py","lineNumber":1446,"sourceCode":"        \"\"\"Unfreeze all parameters for training.\n\n        .. code-block:: python\n\n            model = MyLightningModule(...)\n            model.unfreeze()\n\n        Returns:\n            :class:`LightningModule` self with all parameters unfrozen.\n\n        \"\"\"\n        for param in self.parameters():\n            param.requires_grad = True\n\n        return self.train()\n\n    def _verify_is_manual_optimization(self, fn_name: str) -> None:\n        if self.automatic_optimization:\n            raise MisconfigurationException(\n                f\"to use {fn_name}, please disable automatic optimization:\"\n                \" set model property `automatic_optimization` as False\"\n            )\n\n    @torch.no_grad()\n    def to_onnx(\n        self,\n        file_path: Union[str, Path, BytesIO, None] = None,\n        input_sample: Optional[Any] = None,\n        **kwargs: Any,\n    ) -> Optional[\"ONNXProgram\"]:\n        \"\"\"Saves the model in ONNX format.\n\n        Args:\n            file_path: The path of the file the onnx model should be saved to. Default: None (no file saved).\n            input_sample: An input for tracing. Default: None (Use self.example_input_array)\n\n            **kwargs: Will be passed to torch.onnx.export function.","sourceCodeStart":1428,"sourceCodeEnd":1464,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/core/module.py#L1428-L1464","documentation":"_verify_is_manual_optimization guards manual-optimization-only APIs (notably self.manual_backward). If the module still has automatic_optimization=True, the Trainer owns backward/optimizer steps, so calling manual_backward is contradictory and raises MisconfigurationException.","triggerScenarios":"Calling self.manual_backward(loss) in training_step while self.automatic_optimization is True (the default).","commonSituations":"User added manual_backward for GANs/multiple optimizers or custom scaling without flipping the module flag; copied manual-optimization examples into an automatic-optimization module.","solutions":["Set self.automatic_optimization = False in __init__ before using manual_backward","Then take over the loop: call self.manual_backward(loss), optimizer.step(), optimizer.zero_grad(), and self.optimizers handling yourself","If you don't need manual control, remove manual_backward and just return loss from training_step"],"exampleFix":"# before\nclass M(L.LightningModule):\n    def training_step(self, batch, idx):\n        loss = self.step(batch)\n        self.manual_backward(loss)  # raises\n        return loss\n\n# after\nclass M(L.LightningModule):\n    def __init__(self):\n        super().__init__()\n        self.automatic_optimization = False\n    def training_step(self, batch, idx):\n        loss = self.step(batch)\n        self.manual_backward(loss)\n        self.optimizers().step()\n        self.optimizers().zero_grad()","handlingStrategy":"validation","validationCode":"if not self.automatic_optimization:\n    self.manual_backward(loss)\nelse:\n    return loss  # let the Trainer handle backward","typeGuard":"def is_manual_optimization(module) -> bool:\n    return module.automatic_optimization is False","tryCatchPattern":"from lightning.pytorch.utilities.exceptions import MisconfigurationException\ntry:\n    self.manual_backward(loss)\nexcept MisconfigurationException:\n    raise RuntimeError('set self.automatic_optimization = False in __init__')","preventionTips":["Set automatic_optimization=False in __init__ whenever using manual_backward/optimizer steps","Enforce with an __init_subclass__ or unit test for modules that reference manual_backward"],"tags":["pytorch-lightning","manual-optimization","manual-backward","misconfiguration"],"backgroundTag":"manual-optimization-required","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}