{"record":{"id":"41b13b5e22dce6fc","repo":"Lightning-AI/pytorch-lightning","slug":"str-xla-available-41b13b","errorCode":null,"errorMessage":"str(_XLA_AVAILABLE)","messagePattern":"str\\(_XLA_AVAILABLE\\)","errorType":"exception","errorClass":"ModuleNotFoundError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/plugins/io/xla.py","lineNumber":40,"sourceCode":"\nfrom lightning.fabric.accelerators.xla import _XLA_AVAILABLE\nfrom lightning.fabric.plugins.io.torch_io import TorchCheckpointIO\nfrom lightning.fabric.utilities.cloud_io import get_filesystem\nfrom lightning.fabric.utilities.types import _PATH\n\nlog = logging.getLogger(__name__)\n\n\nclass XLACheckpointIO(TorchCheckpointIO):\n    \"\"\"CheckpointIO that utilizes ``xm.save`` to save checkpoints for TPU training strategies.\n\n    .. warning::  This is an :ref:`experimental <versioning:Experimental API>` feature.\n\n    \"\"\"\n\n    def __init__(self, *args: Any, **kwargs: Any) -> None:\n        if not _XLA_AVAILABLE:\n            raise ModuleNotFoundError(str(_XLA_AVAILABLE))\n        super().__init__(*args, **kwargs)\n\n    @override\n    def save_checkpoint(self, checkpoint: dict[str, Any], path: _PATH, storage_options: Optional[Any] = None) -> None:\n        \"\"\"Save model/training states as a checkpoint file through state-dump and file-write.\n\n        Args:\n            checkpoint: dict containing model and trainer state\n            path: write-target path\n            storage_options: not used in ``XLACheckpointIO.save_checkpoint``\n\n        Raises:\n            TypeError:\n                If ``storage_options`` arg is passed in\n\n        \"\"\"\n        if storage_options is not None:\n            raise TypeError(","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/plugins/io/xla.py#L22-L58","documentation":"Raised by XLACheckpointIO.__init__ when the torch_xla package (XLA support) is not installed. The plugin wrapper for TPU/XLA checkpointing requires torch_xla, and its availability flag (with the import error message) is stringified into this ModuleNotFoundError.","triggerScenarios":"Instantiating XLACheckpointIO (or a Fabric/Trainer config that selects the XLA checkpoint IO plugin) in an environment where `import torch_xla` fails or the package is absent.","commonSituations":"Running on CPU/GPU-only machines, forgetting to install the torch_xla extra (e.g. `pip install lightning[xla]` or torch_xla matching the torch/TPU version), or version mismatch between torch and torch_xla making the import fail.","solutions":["Install torch_xla appropriate for your platform: `pip install lightning[xla]` or the torch_xla wheel matching your torch version","Verify import works: `python -c \"import torch_xla\"` and fix any underlying ImportError it reports","If you don't need TPU/XLA, switch to a different checkpoint IO plugin (TorchCheckpointIO) instead of XLACheckpointIO"],"exampleFix":"# before\nfrom lightning.fabric.plugins.io.xla import XLACheckpointIO\nio = XLACheckpointIO()  # ModuleNotFoundError\n\n# after\n# pip install lightning[xla]\nio = XLACheckpointIO()","handlingStrategy":"validation","validationCode":"from lightning.fabric.plugins.io.xla import _XLA_AVAILABLE\nif not _XLA_AVAILABLE:\n    raise SystemExit(\"torch_xla not available; install lightning[xla] or use TorchCheckpointIO\")","typeGuard":null,"tryCatchPattern":"try:\n    from lightning.fabric.plugins.io.xla import XLACheckpointIO\nexcept (ModuleNotFoundError, ImportError):\n    XLACheckpointIO = None","preventionTips":["Install extras up front: pip install lightning[xla] on TPU setups","Gate plugin selection on _XLA_AVAILABLE before constructing the Fabric/Trainer"],"tags":["xla","tpu","dependency","pytorch-lightning"],"backgroundTag":"missing-optional-dependency","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}