{"record":{"id":"845c812af2bd3eb3","repo":"Lightning-AI/pytorch-lightning","slug":"the-xlaaccelerator-can-only-be-used-with-a-sing-845c81","errorCode":null,"errorMessage":"The `XLAAccelerator` can only be used with a `SingleDeviceXLAStrategy` or `XLAStrategy`, found {self.strategy.__class__.__name__}.","messagePattern":"The `XLAAccelerator` can only be used with a `SingleDeviceXLAStrategy` or `XLAStrategy`, found (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/trainer/connectors/accelerator_connector.py","lineNumber":548,"sourceCode":"        if hasattr(self.strategy, \"set_world_ranks\"):\n            self.strategy.set_world_ranks()\n        self.strategy._configure_launcher()\n\n        if _IS_INTERACTIVE and self.strategy.launcher and not self.strategy.launcher.is_interactive_compatible:\n            raise MisconfigurationException(\n                f\"`Trainer(strategy={self._strategy_flag!r})` is not compatible with an interactive\"\n                \" environment. Run your code as a script, or choose a notebook-compatible strategy:\"\n                f\" `Trainer(strategy='ddp_notebook')`.\"\n                \" In case you are spawning processes yourself, make sure to include the Trainer\"\n                \" creation inside the worker function.\"\n            )\n\n        # TODO: should be moved to _check_strategy_and_fallback().\n        # Current test check precision first, so keep this check here to meet error order\n        if isinstance(self.accelerator, XLAAccelerator) and not isinstance(\n            self.strategy, (SingleDeviceXLAStrategy, XLAStrategy)\n        ):\n            raise ValueError(\n                \"The `XLAAccelerator` can only be used with a `SingleDeviceXLAStrategy` or `XLAStrategy`,\"\n                f\" found {self.strategy.__class__.__name__}.\"\n            )\n\n    @property\n    def is_distributed(self) -> bool:\n        distributed_strategies = [\n            DDPStrategy,\n            FSDPStrategy,\n            DeepSpeedStrategy,\n            ModelParallelStrategy,\n            XLAStrategy,\n        ]\n\n        if isinstance(self.strategy, tuple(distributed_strategies)):\n            return True\n        if hasattr(self.strategy, \"is_distributed\"):\n            # Used for custom plugins. They should implement this property","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/trainer/connectors/accelerator_connector.py#L530-L566","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\ntrainer = Trainer(accelerator=\"tpu\", strategy=\"ddp\")\n# after\ntrainer = Trainer(accelerator=\"tpu\", strategy=\"auto\")\n# or explicitly\nfrom lightning.pytorch.strategies import XLAStrategy\ntrainer = Trainer(accelerator=\"tpu\", strategy=XLAStrategy())","handlingStrategy":"validation","validationCode":"from lightning.pytorch.strategies import SingleDeviceXLAStrategy, XLAStrategy\nfrom lightning.pytorch.accelerators import XLAAccelerator\n\nif isinstance(trainer_kwargs.get(\"accelerator\"), XLAAccelerator) or trainer_kwargs.get(\"accelerator\") == \"tpu\":\n    strat = trainer_kwargs.get(\"strategy\")\n    ok = strat is None or strat in (\"auto\", \"xla\", \"single_device_xla\") or isinstance(strat, (SingleDeviceXLAStrategy, XLAStrategy))\n    assert ok, \"XLAAccelerator requires SingleDeviceXLAStrategy or XLAStrategy\"","typeGuard":"def is_xla_compatible(strategy, accelerator) -> bool:\n    from lightning.pytorch.accelerators import XLAAccelerator\n    from lightning.pytorch.strategies import SingleDeviceXLAStrategy, XLAStrategy\n    if not (accelerator == \"tpu\" or isinstance(accelerator, XLAAccelerator)):\n        return True\n    return strategy is None or isinstance(strategy, (SingleDeviceXLAStrategy, XLAStrategy))","tryCatchPattern":"try:\n    trainer = Trainer(**kwargs)\nexcept ValueError as e:\n    if \"XLAAccelerator\" in str(e):\n        kwargs[\"strategy\"] = \"auto\"\n        trainer = Trainer(**kwargs)\n    else:\n        raise","preventionTips":["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"],"tags":["lightning","tpu","xla","strategy","trainer-init","accelerator"],"backgroundTag":"accelerator-strategy-mismatch","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}