{"record":{"id":"36f50db3ba8bbb8e","repo":"Lightning-AI/pytorch-lightning","slug":"precision-bf16-mixed-does-not-use-a-scaler-fo-36f50d","errorCode":null,"errorMessage":"`precision='bf16-mixed'` does not use a scaler, found {scaler}.","messagePattern":"`precision='bf16-mixed'` does not use a scaler, found (.+?)\\.","errorType":"exception","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/plugins/precision/amp.py","lineNumber":75,"sourceCode":"    \"\"\"\n\n    def __init__(\n        self,\n        precision: Literal[\"16-mixed\", \"bf16-mixed\"],\n        device: str,\n        scaler: Optional[\"torch.amp.GradScaler\"] = None,\n    ) -> None:\n        if precision not in (\"16-mixed\", \"bf16-mixed\"):\n            raise ValueError(\n                f\"`Passed `{type(self).__name__}(precision={precision!r})`.\"\n                f\" Precision must be '16-mixed' or 'bf16-mixed'.\"\n            )\n\n        self.precision = precision\n        if scaler is None and self.precision == \"16-mixed\":\n            scaler = torch.amp.GradScaler(device=device)\n        if scaler is not None and self.precision == \"bf16-mixed\":\n            raise MisconfigurationException(f\"`precision='bf16-mixed'` does not use a scaler, found {scaler}.\")\n        self.device = device\n        self.scaler = scaler\n\n    @override\n    def pre_backward(self, tensor: Tensor, module: \"pl.LightningModule\") -> Tensor:  # type: ignore[override]\n        if self.scaler is not None:\n            tensor = self.scaler.scale(tensor)\n        return super().pre_backward(tensor, module)\n\n    @override\n    def optimizer_step(  # type: ignore[override]\n        self,\n        optimizer: Optimizable,\n        model: \"pl.LightningModule\",\n        closure: Callable[[], Any],\n        **kwargs: Any,\n    ) -> Any:\n        if self.scaler is None:","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/plugins/precision/amp.py#L57-L93","documentation":"MixedPrecisionPlugin (the AMP precision plugin) was constructed with a GradScaler while precision is 'bf16-mixed'. Bfloat16 training has a much wider dynamic range than fp16, so loss scaling is unnecessary, and Lightning rejects the scaler to prevent silently mis-scaled gradients. Pass scaler=None (or omit it) when using bf16.","triggerScenarios":"Instantiating MixedPrecisionPlugin(precision='bf16-mixed', scaler=torch.amp.GradScaler(...)) or a custom plugin subclass; also when reusing an fp16 ('16-mixed') plugin config after switching Trainer(precision='bf16-mixed').","commonSituations":"Migrating a working 16-mixed AMP setup to bf16-mixed without removing the scaler; copy-pasted plugin configs from older Lightning versions (<2.0) where scaler+bf16 was tolerated; programmatically swapping precision strings while keeping a scaler object.","solutions":["Remove the scaler argument when using precision='bf16-mixed'","If you need a scaler, switch precision to '16-mixed'","Build the scaler conditionally: only create one when precision == '16-mixed'"],"exampleFix":"# before\nplugin = MixedPrecisionPlugin(precision='bf16-mixed', scaler=torch.amp.GradScaler('cuda'))\n\n# after\nplugin = MixedPrecisionPlugin(precision='bf16-mixed', scaler=None)","handlingStrategy":"validation","validationCode":"from lightning.pytorch.plugins import MixedPrecisionPlugin\n\ndef make_plugin(precision, scaler=None):\n    if precision == '16-mixed' and scaler is None:\n        scaler = torch.amp.GradScaler('cuda')\n    if precision != '16-mixed':\n        scaler = None  # bf16/fp32 never take a scaler\n    return MixedPrecisionPlugin(precision=precision, scaler=scaler)","typeGuard":"def is_scaler_compatible_precision(precision: str) -> bool:\n    return precision == '16-mixed'","tryCatchPattern":null,"preventionTips":["Never hardcode a GradScaler in shared configs; derive it from the precision string","Treat 'bf16-mixed' as scaler-free by design, not as an error to work around"],"tags":["pytorch-lightning","amp","bf16","mixed-precision","gradscaler","plugin"],"backgroundTag":"mixed-precision-config-mismatch","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}