{"record":{"id":"cc72e37955163312","repo":"Lightning-AI/pytorch-lightning","slug":"fsdpstrategy-save-checkpoint-storage-options","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":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/fsdp.py","lineNumber":441,"sourceCode":"\n    @override\n    def save_checkpoint(\n        self,\n        path: _PATH,\n        state: dict[str, Union[Module, Optimizer, Any]],\n        storage_options: Optional[Any] = None,\n        filter: Optional[dict[str, Callable[[str, Any], bool]]] = None,\n    ) -> None:\n        \"\"\"Save model, optimizer, and other state to a checkpoint on disk.\n\n        If the state-dict-type is ``'full'``, the checkpoint will be written to a single file containing the weights,\n        optimizer state and other metadata. If the state-dict-type is ``'sharded'``, the checkpoint gets saved as a\n        directory containing one file per process, with model- and optimizer shards stored per file. Additionally, it\n        creates a metadata file `meta.pt` with the rest of the user's state (only saved from rank 0).\n\n        \"\"\"\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        if filter is not None and self._state_dict_type == \"sharded\":\n            # https://github.com/pytorch/pytorch/issues/105379\n            raise NotImplementedError(\n                \"FSDP doesn't support loading sharded filtered checkpoints, so saving them is disabled.\"\n            )\n\n        # broadcast the path from rank 0 to ensure all the states are saved in a common path\n        path = _resolve_path(self.broadcast(path))\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        from torch.distributed.fsdp import FullyShardedDataParallel as FSDP\n\n        modules = [module for module in state.values() if _has_fsdp_modules(module)]\n        if len(modules) == 0:","sourceCodeStart":423,"sourceCodeEnd":459,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/fsdp.py#L423-L459","documentation":"FSDPStrategy does not use the CheckpointIO plugin, so per-call storage_options in save_checkpoint have no effect; passing them raises TypeError rather than silently ignoring the option.","triggerScenarios":"strategy.save_checkpoint(path, state, storage_options={...}) — often inherited from code written for other strategies (e.g. fsspec/S3 options with XLAS/Async checkpoint IO).","commonSituations":"Shared checkpoint utility that passes storage_options for S3/GCS for all strategies; migrating from DDPStrategy where storage_options reached the TorchFilesystemCheckpointIO.","solutions":["Drop storage_options for FSDP saves; configure the filesystem at the path level (mount, fsspec URL) instead","If you need remote storage, save locally then copy/upload the directory afterwards","Branch your utility: skip storage_options when strategy is FSDPStrategy"],"exampleFix":"# before\nstrategy.save_checkpoint(path, state, storage_options={\"anon\": True})\n\n# after\nstrategy.save_checkpoint(path, state)\n# then upload the directory to remote storage separately","handlingStrategy":"validation","validationCode":"from lightning.fabric.strategies import FSDPStrategy\nif isinstance(fabric.strategy, FSDPStrategy):\n    strategy.save_checkpoint(path, state)  # no storage_options\nelse:\n    strategy.save_checkpoint(path, state, storage_options=opts)","typeGuard":"from lightning.fabric.strategies import FSDPStrategy\ndef supports_storage_options(strategy) -> bool:\n    return not isinstance(strategy, FSDPStrategy)","tryCatchPattern":null,"preventionTips":["Make storage_options conditional on strategy type","Handle remote upload as a post-save step for FSDP"],"tags":["fsdp","checkpoint","storage-options","save"],"backgroundTag":"unsupported-argument","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}