Lightning-AI/pytorch-lightning · error · ValueError

`precision={precision!r}` does not use a scaler, found {scal

Error message

`precision={precision!r}` does not use a scaler, found {scaler}.

What it means

FSDPPrecision only uses a GradScaler with '16-mixed' precision. If you explicitly pass a scaler instance while using any other precision (e.g. 'bf16-mixed' or '32-true'), the constructor raises this ValueError because the scaler would never be used.

Source

Thrown at src/lightning/fabric/plugins/precision/fsdp.py:64

    Raises:
        ValueError:
            If unsupported ``precision`` is provided.

    """

    def __init__(self, precision: _PRECISION_INPUT, scaler: Optional["ShardedGradScaler"] = None) -> None:
        supported_precision = get_args(_PRECISION_INPUT)
        if precision not in supported_precision:
            raise ValueError(
                f"`precision={precision!r})` is not supported in FSDP."
                f" `precision` must be one of: {supported_precision}."
            )

        from torch.distributed.fsdp.sharded_grad_scaler import ShardedGradScaler

        if scaler is not None and self.precision != "16-mixed":
            raise ValueError(f"`precision={precision!r}` does not use a scaler, found {scaler}.")

        self.scaler = ShardedGradScaler() if scaler is None and precision == "16-mixed" else None
        self.precision = precision

        precision_to_type = {
            "bf16-mixed": torch.float32,
            "16-mixed": torch.float32,
            "bf16-true": torch.bfloat16,
            "16-true": torch.float16,
            "32-true": torch.float32,
        }
        self._desired_input_dtype = precision_to_type[self.precision]

    @override
    def convert_module(self, module: Module) -> Module:
        if "true" in self.precision:
            return module.to(dtype=self._desired_input_dtype)
        return module

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Remove the scaler argument when precision is not '16-mixed' (bfloat16/32 do not need loss scaling)
2. Only construct and pass a ShardedGradScaler when precision == '16-mixed'
3. Let the plugin auto-create the scaler by passing scaler=None with '16-mixed'

Example fix

# before
precision = FSDPPrecision(precision="bf16-mixed", scaler=ShardedGradScaler())
# after
precision = FSDPPrecision(precision="bf16-mixed")

if scaler is not None and precision != "16-mixed":
    raise ValueError("scaler only valid with 16-mixed")
plugin = FSDPPrecision(precision, scaler=scaler if precision == "16-mixed" else None)

def scaler_compatible(precision: str, scaler: object) -> bool:
    return scaler is None or precision == "16-mixed"

try:
    plugin = FSDPPrecision(precision, scaler=scaler)
except ValueError:
    plugin = FSDPPrecision(precision)

When it happens

Trigger: Calling FSDPPrecision(precision='bf16-mixed', scaler=ShardedGradScaler()) — i.e. providing a non-None scaler together with a precision other than '16-mixed'.

Common situations: Copy-pasting a 16-mixed setup when switching to bf16; programmatically passing a scaler regardless of precision setting.

Related errors

• `precision={precision!r})` is not supported in FSDP. `precis
• Gradient clipping is not implemented for optimizers handling
• `precision={precision!r})` is not supported in FSDP. `precis
• The optimizer has references to the model's meta-device para
• Passed `{type(self).__name__}(precision={precision!r})`. Pre

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/73219ab7c519761c. Report an issue: GitHub.