Lightning-AI/pytorch-lightning · error · ValueError

The `XLAAccelerator` can only be used with a `SingleDeviceXL

Error message

The `XLAAccelerator` can only be used with a `SingleDeviceXLAStrategy` or `XLAStrategy`, found {self.strategy.__class__.__name__}.

What it means

Raised by AcceleratorConnector during Trainer.__init__ when an XLAAccelerator (TPU) is paired with a strategy that is not SingleDeviceXLAStrategy or XLAStrategy. The XLA accelerator requires XLA-specific strategy logic (device setup, mesh initialization) that generic strategies like DDP do not provide. Lightning therefore refuses to construct the Trainer rather than failing later at device placement time.

Source

Thrown at src/lightning/pytorch/trainer/connectors/accelerator_connector.py:548

        if hasattr(self.strategy, "set_world_ranks"):
            self.strategy.set_world_ranks()
        self.strategy._configure_launcher()

        if _IS_INTERACTIVE and self.strategy.launcher and not self.strategy.launcher.is_interactive_compatible:
            raise MisconfigurationException(
                f"`Trainer(strategy={self._strategy_flag!r})` is not compatible with an interactive"
                " environment. Run your code as a script, or choose a notebook-compatible strategy:"
                f" `Trainer(strategy='ddp_notebook')`."
                " In case you are spawning processes yourself, make sure to include the Trainer"
                " creation inside the worker function."
            )

        # TODO: should be moved to _check_strategy_and_fallback().
        # Current test check precision first, so keep this check here to meet error order
        if isinstance(self.accelerator, XLAAccelerator) and not isinstance(
            self.strategy, (SingleDeviceXLAStrategy, XLAStrategy)
        ):
            raise ValueError(
                "The `XLAAccelerator` can only be used with a `SingleDeviceXLAStrategy` or `XLAStrategy`,"
                f" found {self.strategy.__class__.__name__}."
            )

    @property
    def is_distributed(self) -> bool:
        distributed_strategies = [
            DDPStrategy,
            FSDPStrategy,
            DeepSpeedStrategy,
            ModelParallelStrategy,
            XLAStrategy,
        ]

        if isinstance(self.strategy, tuple(distributed_strategies)):
            return True
        if hasattr(self.strategy, "is_distributed"):
            # Used for custom plugins. They should implement this property

View on GitHub (pinned to 9fed5c27d2)

Solutions

Remove the explicit strategy argument and let Lightning auto-select SingleDeviceXLAStrategy/XLAStrategy for accelerator="tpu"
Pass a compatible strategy explicitly: Trainer(accelerator="tpu", strategy=XLAStrategy()) or SingleDeviceXLAStrategy()
Use accelerator="auto" with strategy="auto" so both are resolved consistently
If you meant a different device (GPU/CPU), remove the XLA accelerator/TPU setting

Example fix

# before
trainer = Trainer(accelerator="tpu", strategy="ddp")
# after
trainer = Trainer(accelerator="tpu", strategy="auto")
# or explicitly
from lightning.pytorch.strategies import XLAStrategy
trainer = Trainer(accelerator="tpu", strategy=XLAStrategy())

Defensive patterns

Strategy: validation

Validate before calling

from lightning.pytorch.strategies import SingleDeviceXLAStrategy, XLAStrategy
from lightning.pytorch.accelerators import XLAAccelerator

if isinstance(trainer_kwargs.get("accelerator"), XLAAccelerator) or trainer_kwargs.get("accelerator") == "tpu":
    strat = trainer_kwargs.get("strategy")
    ok = strat is None or strat in ("auto", "xla", "single_device_xla") or isinstance(strat, (SingleDeviceXLAStrategy, XLAStrategy))
    assert ok, "XLAAccelerator requires SingleDeviceXLAStrategy or XLAStrategy"

Type guard

def is_xla_compatible(strategy, accelerator) -> bool:
    from lightning.pytorch.accelerators import XLAAccelerator
    from lightning.pytorch.strategies import SingleDeviceXLAStrategy, XLAStrategy
    if not (accelerator == "tpu" or isinstance(accelerator, XLAAccelerator)):
        return True
    return strategy is None or isinstance(strategy, (SingleDeviceXLAStrategy, XLAStrategy))

Try / catch

try:
    trainer = Trainer(**kwargs)
except ValueError as e:
    if "XLAAccelerator" in str(e):
        kwargs["strategy"] = "auto"
        trainer = Trainer(**kwargs)
    else:
        raise

Prevention

Prefer accelerator="auto", strategy="auto" in shared configs
Assert accelerator/strategy compatibility in a config factory before building the Trainer
Keep TPU-specific trainer configs separate from GPU ones

When it happens

Trigger: Passing Trainer(accelerator="tpu") or XLAAccelerator() together with strategy="ddp", DDPStrategy, SingleDeviceStrategy, DeepSpeedStrategy, or any other non-XLA strategy. Also occurs when strategy is auto-resolved to a non-XLA default because the accelerator was set explicitly while the strategy string implies a different device.

Common situations: Porting a GPU training script to TPU by only changing accelerator="tpu" while leaving strategy="ddp"; mixing plugins like DeepSpeed with TPU hardware; upgrading Lightning where strategy selection behavior changed.

Related errors

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