{"record":{"id":"d87fa5cbd6a67365","repo":"Lightning-AI/pytorch-lightning","slug":"trainer-save-checkpoint-storage-options-d87fa5","errorCode":null,"errorMessage":"`Trainer.save_checkpoint(..., storage_options=...)` with `storage_options` arg is not supported for `{self.__class__.__name__}`. Please implement your custom `CheckpointIO` to define how you'd like to use `storage_options`.","messagePattern":"`Trainer\\.save_checkpoint\\(\\.\\.\\., storage_options=\\.\\.\\.\\)` with `storage_options` arg is not supported for `(.+?)`\\. Please implement your custom `CheckpointIO` to define how you'd like to use `storage_options`\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/plugins/io/xla.py","lineNumber":58,"sourceCode":"            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(\n                \"`Trainer.save_checkpoint(..., storage_options=...)` with `storage_options` arg\"\n                f\" is not supported for `{self.__class__.__name__}`. Please implement your custom `CheckpointIO`\"\n                \" to define how you'd like to use `storage_options`.\"\n            )\n        fs = get_filesystem(path)\n        fs.makedirs(os.path.dirname(path), exist_ok=True)\n        if RequirementCache(\"omegaconf\"):\n            # workaround for https://github.com/pytorch/xla/issues/2773\n            from omegaconf import DictConfig, ListConfig, OmegaConf\n\n            checkpoint = apply_to_collection(checkpoint, (DictConfig, ListConfig), OmegaConf.to_container)\n        import torch_xla.core.xla_model as xm\n\n        cpu_data = xm._maybe_convert_to_cpu(checkpoint, convert=True)\n        log.debug(f\"Saving checkpoint: {path}\")\n        torch.save(cpu_data, path)\n","sourceCodeStart":40,"sourceCodeEnd":75,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/plugins/io/xla.py#L40-L75","documentation":"XLACheckpointIO.save_checkpoint raises TypeError when a storage_options argument is passed, because the XLA checkpoint implementation has no way to forward arbitrary storage options to the xm.save/xla filesystem layer.","triggerScenarios":"Calling fabric.save_checkpoint(...) / trainer.save_checkpoint(...) with storage_options=... while the XLACheckpointIO plugin is active, or calling XLACheckpointIO.save_checkpoint(path, storage_options={...}) directly.","commonSituations":"Copying storage_options usage (e.g. for fsspec/S3 options) from a TorchCheckpointIO setup onto a TPU/XLA run; passing remote-fs credentials options that work with other plugins.","solutions":["Remove the storage_options argument when saving checkpoints on XLA","If you need storage_options, subclass XLACheckpointIO (or implement CheckpointIO) and handle storage_options yourself","Save locally then upload to remote storage manually after xm.save completes"],"exampleFix":"# before\nfabric.save_checkpoint(path, storage_options={\"rkwargs\": {\"aws_access_key_id\": ...}})\n\n# after\nfabric.save_checkpoint(path)","handlingStrategy":"type-guard","validationCode":"from lightning.fabric.plugins.io.xla import XLACheckpointIO\nfrom lightning.fabric.plugins.io import CheckpointIO\n\ndef supports_storage_options(io) -> bool:\n    import inspect\n    sig = inspect.signature(io.save_checkpoint)\n    return \"storage_options\" in sig.parameters and type(io) is not XLACheckpointIO","typeGuard":"def is_xla_checkpoint_io(io) -> bool:\n    \"TypeGuard[XLACheckpointIO]\"\n    from lightning.fabric.plugins.io.xla import XLACheckpointIO\n    return isinstance(io, XLACheckpointIO)","tryCatchPattern":"try:\n    fabric.save_checkpoint(path, storage_options=opts)\nexcept TypeError as e:\n    if \"storage_options\" in str(e):\n        fabric.save_checkpoint(path)  # fallback: save without options\n    else:\n        raise","preventionTips":["Only pass storage_options with plugins that document support (TorchCheckpointIO/fsspec-based)","Branch on the active checkpoint IO plugin before passing storage_options"],"tags":["xla","checkpoint","storage-options","pytorch-lightning"],"backgroundTag":"unsupported-argument","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}