{"record":{"id":"183f59b057486f63","repo":"Lightning-AI/pytorch-lightning","slug":"precision-precision-r-does-not-use-a-scaler-f-183f59","errorCode":null,"errorMessage":"`precision={precision!r}` does not use a scaler, found {scaler}.","messagePattern":"`precision=(.+?)` does not use a scaler, found (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/plugins/precision/fsdp.py","lineNumber":64,"sourceCode":"\n    Raises:\n        ValueError:\n            If unsupported ``precision`` is provided.\n\n    \"\"\"\n\n    def __init__(self, precision: _PRECISION_INPUT, scaler: Optional[\"ShardedGradScaler\"] = None) -> None:\n        supported_precision = get_args(_PRECISION_INPUT)\n        if precision not in supported_precision:\n            raise ValueError(\n                f\"`precision={precision!r})` is not supported in FSDP.\"\n                f\" `precision` must be one of: {supported_precision}.\"\n            )\n\n        from torch.distributed.fsdp.sharded_grad_scaler import ShardedGradScaler\n\n        if scaler is not None and self.precision != \"16-mixed\":\n            raise ValueError(f\"`precision={precision!r}` does not use a scaler, found {scaler}.\")\n\n        self.scaler = ShardedGradScaler() if scaler is None and precision == \"16-mixed\" else None\n        self.precision = precision\n\n        precision_to_type = {\n            \"bf16-mixed\": torch.float32,\n            \"16-mixed\": torch.float32,\n            \"bf16-true\": torch.bfloat16,\n            \"16-true\": torch.float16,\n            \"32-true\": torch.float32,\n        }\n        self._desired_input_dtype = precision_to_type[self.precision]\n\n    @override\n    def convert_module(self, module: Module) -> Module:\n        if \"true\" in self.precision:\n            return module.to(dtype=self._desired_input_dtype)\n        return module","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/plugins/precision/fsdp.py#L46-L82","documentation":"FSDPMixedPrecisionPlugin received an explicit ShardedGradScaler while precision is anything other than '16-mixed'. Only fp16 mixed precision needs loss scaling; bf16/fp32 modes must be constructed without a scaler, so the plugin raises to prevent a mis-scaled FSDP run.","triggerScenarios":"FSDPMixedPrecisionPlugin(precision='bf16-mixed', scaler=ShardedGradScaler()) or precision='32-true' with a scaler; any non-'16-mixed' precision combined with a non-None scaler argument.","commonSituations":"Switching an FSDP fp16 recipe to bf16-mixed but keeping the ShardedGradScaler in the config; templated plugin construction that always passes a scaler; older examples that shipped with explicit scalers.","solutions":["Pass scaler=None (or omit it) when precision is not '16-mixed'","Keep the scaler only for precision='16-mixed'","Construct the scaler conditionally based on the precision string"],"exampleFix":"# before\nplugin = FSDPMixedPrecisionPlugin(precision='bf16-mixed', scaler=ShardedGradScaler())\n\n# after\nplugin = FSDPMixedPrecisionPlugin(precision='bf16-mixed', scaler=None)","handlingStrategy":"validation","validationCode":"def make_fsdp_plugin(precision, scaler=None):\n    if precision != '16-mixed':\n        scaler = None  # only fp16 mixed precision uses ShardedGradScaler\n    return FSDPMixedPrecisionPlugin(precision=precision, scaler=scaler)","typeGuard":"def scaler_allowed_for(precision: str) -> bool:\n    return precision == '16-mixed'","tryCatchPattern":null,"preventionTips":["Never carry a ShardedGradScaler across precision changes in FSDP configs","Regenerate the whole plugin object when precision changes instead of mutating fields"],"tags":["pytorch-lightning","fsdp","shardedgradscaler","mixed-precision","bf16"],"backgroundTag":"mixed-precision-config-mismatch","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}