Lightning-AI/pytorch-lightning · error · ValueError

`precision={precision!r})` is not supported in XLA. `precisi

Error message

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

What it means

XLAPrecision only accepts the literal precision strings defined in _PRECISION_INPUT (e.g. '32-true', '16-true', 'bf16-true'). Passing any other value (such as '16-mixed', which XLA does not implement via this plugin) raises this ValueError in the constructor.

Source

Thrown at src/lightning/pytorch/plugins/precision/xla.py:47

class XLAPrecision(Precision):
    """Plugin for training with XLA.

    Args:
        precision: Full precision (32-true) or half precision (16-true, bf16-true).

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

    """

    def __init__(self, precision: _PRECISION_INPUT = "32-true") -> None:
        if not _XLA_AVAILABLE:
            raise ModuleNotFoundError(str(_XLA_AVAILABLE))

        supported_precision = get_args(_PRECISION_INPUT)
        if precision not in supported_precision:
            raise ValueError(
                f"`precision={precision!r})` is not supported in XLA."
                f" `precision` must be one of: {supported_precision}."
            )
        self.precision = precision

        if precision == "16-true":
            os.environ["XLA_USE_F16"] = "1"
            self._desired_dtype = torch.float16
        elif precision == "bf16-true":
            os.environ["XLA_USE_BF16"] = "1"
            self._desired_dtype = torch.bfloat16
        else:
            self._desired_dtype = torch.float32

    @override
    def optimizer_step(  # type: ignore[override]
        self,
        optimizer: Optimizable,

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Use a true-precision value supported on XLA: '32-true' or '16-true' (and bf16-true where supported)
2. Check the allowed set programmatically: from typing import get_args; get_args(XLAPrecision.__init__.__annotations__['precision'])
3. For mixed precision on TPU, rely on torch_xla's own AMP handling rather than this plugin's precision argument

Example fix

# before
plugin = XLAPrecision(precision="16-mixed")  # ValueError

# after
plugin = XLAPrecision(precision="16-true")

from typing import get_args
from lightning.pytorch.plugins.precision.xla import _PRECISION_INPUT
assert precision in get_args(_PRECISION_INPUT), f"bad precision {precision}"

def is_valid_xla_precision(p: str) -> bool:
    from typing import get_args
    from lightning.pytorch.plugins.precision.xla import _PRECISION_INPUT
    return p in get_args(_PRECISION_INPUT)

try:
    XLAPrecision(precision=p)
except ValueError as e:
    # log and fall back to a supported precision
    XLAPrecision(precision="32-true")

When it happens

Trigger: Calling XLAPrecision(precision='16-mixed') or Trainer(precision='16-mixed', strategy='xla', ...) where the XLA plugin is selected; any string not in get_args(_PRECISION_INPUT).

Common situations: Copying a GPU training config using '16-mixed' or 'bf16-mixed' to a TPU run; assuming Lightning's mixed-precision strings work identically on XLA.

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

• `precision={precision!r})` is not supported in XLA. `precisi
• You requested to find {num_devices} devices but this machine
• str(_XLA_AVAILABLE)
• `Trainer.save_checkpoint(..., storage_options=...)` with `st
• 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/e87cb8d166384f37. Report an issue: GitHub.