{"record":{"id":"ec4cecf5ac5b218c","repo":"Lightning-AI/pytorch-lightning","slug":"trainer-save-checkpoint-storage-options-ec4cec","errorCode":null,"errorMessage":"`Trainer.save_checkpoint(..., storage_options=...)` with `storage_options` arg is not supported for `{self.__class__.__name__}` as `CheckpointIO` is not used.","messagePattern":"`Trainer\\.save_checkpoint\\(\\.\\.\\., storage_options=\\.\\.\\.\\)` with `storage_options` arg is not supported for `(.+?)` as `CheckpointIO` is not used\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/strategies/deepspeed.py","lineNumber":652,"sourceCode":"    @override\n    def save_checkpoint(self, checkpoint: dict, filepath: _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: The checkpoint state dictionary\n            filepath: write-target file's path\n            storage_options: not used for ``DeepSpeedStrategy`` as ``CheckpointIO`` is not used\n\n        Raises:\n            TypeError:\n                If ``storage_options`` arg is passed in\n\n        \"\"\"\n        # broadcast the filepath from rank 0 to ensure all the states are saved in a common filepath\n        filepath = self.broadcast(filepath)\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__}` as `CheckpointIO` is not used.\"\n            )\n\n        if self.zero_stage_3 and self._multi_device and self.is_global_zero:\n            warning_cache.warn(\n                \"When saving the DeepSpeed Stage 3 checkpoint, \"\n                \"each worker will save a shard of the checkpoint within a directory. \"\n                \"If a single file is required after training, \"\n                \"see https://lightning.ai/docs/pytorch/stable/advanced/model_parallel.html#\"\n                \"deepspeed-zero-stage-3-single-file for instructions.\"\n            )\n        # Use deepspeed's internal checkpointing function to handle partitioned weights across processes\n        # dump states as a checkpoint dictionary object\n        _exclude_keys = [\"state_dict\", \"optimizer_states\"]\n        checkpoint = {k: v for k, v in checkpoint.items() if k not in _exclude_keys}\n        self.deepspeed_engine.save_checkpoint(\n            filepath,","sourceCodeStart":634,"sourceCodeEnd":670,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/strategies/deepspeed.py#L634-L670","documentation":"DeepSpeedStrategy saves checkpoints through DeepSpeed's own pipeline (a `CheckpointIO` plugin is not used), so there is nowhere to hand per-storage backend options. Passing `storage_options` (designed for fsspec-based checkpoint plugins like Async or filesystem-specific IO) raises TypeError.","triggerScenarios":"`trainer.save_checkpoint(path, storage_options={...})` (or `strategy.save_checkpoint(..., storage_options=...)`) while the strategy is DeepSpeedStrategy.","commonSituations":"Code shared across strategies that always passes storage_options (e.g. for saving to S3 via the TorchX/Async plugin); switching a working FSDP run to DeepSpeed without removing the kwarg.","solutions":["Drop `storage_options` when using DeepSpeedStrategy","If you need remote/custom storage, copy the checkpoint after saving, or use a strategy that supports CheckpointIO","Branch on strategy type before calling save_checkpoint"],"exampleFix":"# before\ntrainer.save_checkpoint(ckpt, storage_options={\"fs\": s3fs})  # DeepSpeedStrategy\n\n# after\ntrainer.save_checkpoint(ckpt)\n# upload ckpt dir to remote storage afterwards if needed","handlingStrategy":"validation","validationCode":"from lightning.pytorch.strategies import DeepSpeedStrategy\nif isinstance(trainer.strategy, DeepSpeedStrategy):\n    trainer.save_checkpoint(path)  # no storage_options\nelse:\n    trainer.save_checkpoint(path, storage_options=opts)","typeGuard":"def supports_storage_options(trainer) -> bool:\n    return getattr(trainer.strategy, \"checkpoint_io\", None) is not None","tryCatchPattern":null,"preventionTips":["Branch on strategy type before passing storage_options","Keep checkpoint-upload logic separate from save calls"],"tags":["deepspeed","save-checkpoint","storage-options","checkpointio"],"backgroundTag":"unsupported-kwarg","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}