{"record":{"id":"284d243a9b091615","repo":"Lightning-AI/pytorch-lightning","slug":"fsdpstrategy-save-checkpoint-storage-options-284d24","errorCode":null,"errorMessage":"`FSDPStrategy.save_checkpoint(..., storage_options=...)` is not supported because `FSDPStrategy` does not use the `CheckpointIO`.","messagePattern":"`FSDPStrategy\\.save_checkpoint\\(\\.\\.\\., storage_options=\\.\\.\\.\\)` is not supported because `FSDPStrategy` does not use the `CheckpointIO`\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/strategies/fsdp.py","lineNumber":570,"sourceCode":"                state_dict = FSDP.optim_state_dict(self.model, optimizer)\n                if self.global_rank == 0:\n                    # Store the optimizer state dict in standard format\n                    state_dict = FSDP.rekey_optim_state_dict(state_dict, OptimStateKeyType.PARAM_ID, self.model)\n                return state_dict\n\n        raise ValueError(f\"Unknown state_dict_type: {self._state_dict_type}\")\n\n    @override\n    def load_optimizer_state_dict(self, checkpoint: Mapping[str, Any]) -> None:\n        # Override to do nothing, the FSDP already loaded the states in `load_checkpoint()`\n        pass\n\n    @override\n    def save_checkpoint(\n        self, checkpoint: dict[str, Any], filepath: _PATH, storage_options: Optional[Any] = None\n    ) -> None:\n        if storage_options is not None:\n            raise TypeError(\n                \"`FSDPStrategy.save_checkpoint(..., storage_options=...)` is not supported because\"\n                \" `FSDPStrategy` does not use the `CheckpointIO`.\"\n            )\n\n        path = _resolve_path(self.broadcast(filepath))\n        if self._state_dict_type == \"full\" and _is_checkpoint_dir(path) and not _is_sharded_checkpoint(path):\n            raise IsADirectoryError(f\"The checkpoint path exists and is a directory: {path}\")\n\n        if self._state_dict_type == \"sharded\":\n            _prepare_directory_checkpoint(path)\n\n            converted_state = {\"model\": checkpoint.pop(\"state_dict\")}\n            converted_state.update({\n                f\"optimizer_{idx}\": optim_state\n                for idx, optim_state in enumerate(checkpoint.pop(\"optimizer_states\", []))\n            })\n\n            _distributed_checkpoint_save(converted_state, path)","sourceCodeStart":552,"sourceCodeEnd":588,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/strategies/fsdp.py#L552-L588","documentation":"FSDPStrategy implements checkpoint saving itself (sharded dirs or consolidated files via torch.distributed.checkpoint) and does not route through the CheckpointIO plugin abstraction, so per-backend `storage_options` cannot be honored and passing them raises TypeError.","triggerScenarios":"`trainer.save_checkpoint(path, storage_options=...)` or `strategy.save_checkpoint(checkpoint, filepath, storage_options=...)` while training under FSDPStrategy.","commonSituations":"Shared checkpoint utility code that passes storage_options for fsspec/S3 backends; pipelines written for AsyncCheckpointIO reused with FSDP.","solutions":["Remove `storage_options` from the save_checkpoint call under FSDP","Handle remote upload after the local save completes","Switch strategy or checkpoint plugin if backend-specific options are required"],"exampleFix":"# before\ntrainer.save_checkpoint(\"ckpt\", storage_options={\"auto_mkdir\": True})\n\n# after\ntrainer.save_checkpoint(\"ckpt\")","handlingStrategy":"validation","validationCode":"from lightning.pytorch.strategies import FSDPStrategy\nif isinstance(trainer.strategy, FSDPStrategy):\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":["Strategy-branch before passing storage_options","Move remote-upload logic outside save_checkpoint"],"tags":["fsdp","save-checkpoint","storage-options"],"backgroundTag":"unsupported-kwarg","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}