Lightning-AI/pytorch-lightning · error · ValueError

`precision={precision!r})` is not supported in FSDP. `precis

Error message

`precision={precision!r})` is not supported in FSDP. `precision` must be one of: {supported_precision}.

What it means

FSDPPrecision.__init__ validates the precision argument against the _PRECISION_INPUT literal tuple. Any string not exactly matching a supported precision mode (typically '16-mixed' or 'bf16-mixed' for FSDP) raises this ValueError immediately.

Source

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

    """Precision plugin for training with Fully Sharded Data Parallel (FSDP).

    .. warning::  This is an :ref:`experimental <versioning:Experimental API>` feature.

    Args:
        precision: Full precision (32-true), half precision (16-true, bf16-true) or
            mixed precision (16-mixed, bf16-mixed).
        scaler: An optional :class:`torch.distributed.fsdp.sharded_grad_scaler.ShardedGradScaler` to use.

    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,

View on GitHub (pinned to 9fed5c27d2)

Solutions

Use an exact supported literal such as 'bf16-mixed' or '16-mixed'
Print typing.get_args(lightning.fabric.plugins.precision.fsdp._PRECISION_INPUT) to confirm the accepted values for your version
Normalize user-supplied precision strings in your config layer before building the strategy

Example fix

# before
strategy = FSDPPStrategy(precision="bf16")
# after
strategy = FSDPPStrategy(precision="bf16-mixed")

Defensive patterns

Strategy: validation

Validate before calling

from typing import get_args
from lightning.fabric.plugins.precision.fsdp import _PRECISION_INPUT
if precision not in get_args(_PRECISION_INPUT):
    raise ValueError(f"unsupported precision {precision!r}")

Type guard

from typing import get_args
from lightning.fabric.plugins.precision.fsdp import _PRECISION_INPUT

def is_valid_precision(p: object) -> bool:
    return isinstance(p, str) and p in get_args(_PRECISION_INPUT)

Try / catch

try:
    plugin = FSDPPrecision(precision)
except ValueError:
    # log and fall back to a known-good mode
    plugin = FSDPPrecision("bf16-mixed")

Prevention

Never pass torch dtypes or ints as precision
Use shared constants for precision strings across the project

When it happens

Trigger: Constructing FSDPPrecision(precision=...) or FSDPPStrategy(precision=...) with a value such as 'fp16', 'bf16', 16, or '32' that is not in get_args(_PRECISION_INPUT).

Common situations: Migrating configs from older Lightning versions or other frameworks that use 'fp16'/'bf16'; passing an int or torch.dtype where a precision string is expected.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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