Lightning-AI/pytorch-lightning · error · TypeError

`FSDPStrategy.save_checkpoint(..., storage_options=...)` is

Error message

`FSDPStrategy.save_checkpoint(..., storage_options=...)` is not supported because `FSDPStrategy` does not use the `CheckpointIO`.

What it means

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.

Source

Thrown at src/lightning/fabric/strategies/fsdp.py:441

    @override
    def save_checkpoint(
        self,
        path: _PATH,
        state: dict[str, Union[Module, Optimizer, Any]],
        storage_options: Optional[Any] = None,
        filter: Optional[dict[str, Callable[[str, Any], bool]]] = None,
    ) -> None:
        """Save model, optimizer, and other state to a checkpoint on disk.

        If the state-dict-type is ``'full'``, the checkpoint will be written to a single file containing the weights,
        optimizer state and other metadata. If the state-dict-type is ``'sharded'``, the checkpoint gets saved as a
        directory containing one file per process, with model- and optimizer shards stored per file. Additionally, it
        creates a metadata file `meta.pt` with the rest of the user's state (only saved from rank 0).

        """
        if storage_options is not None:
            raise TypeError(
                "`FSDPStrategy.save_checkpoint(..., storage_options=...)` is not supported because"
                " `FSDPStrategy` does not use the `CheckpointIO`."
            )
        if filter is not None and self._state_dict_type == "sharded":
            # https://github.com/pytorch/pytorch/issues/105379
            raise NotImplementedError(
                "FSDP doesn't support loading sharded filtered checkpoints, so saving them is disabled."
            )

        # broadcast the path from rank 0 to ensure all the states are saved in a common path
        path = _resolve_path(self.broadcast(path))
        if self._state_dict_type == "full" and _is_checkpoint_dir(path) and not _is_sharded_checkpoint(path):
            raise IsADirectoryError(f"The checkpoint path exists and is a directory: {path}")

        from torch.distributed.fsdp import FullyShardedDataParallel as FSDP

        modules = [module for module in state.values() if _has_fsdp_modules(module)]
        if len(modules) == 0:

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Drop storage_options for FSDP saves; configure the filesystem at the path level (mount, fsspec URL) instead
2. If you need remote storage, save locally then copy/upload the directory afterwards
3. Branch your utility: skip storage_options when strategy is FSDPStrategy

Example fix

# before
strategy.save_checkpoint(path, state, storage_options={"anon": True})

# after
strategy.save_checkpoint(path, state)
# then upload the directory to remote storage separately

from lightning.fabric.strategies import FSDPStrategy
if isinstance(fabric.strategy, FSDPStrategy):
    strategy.save_checkpoint(path, state)  # no storage_options
else:
    strategy.save_checkpoint(path, state, storage_options=opts)

from lightning.fabric.strategies import FSDPStrategy
def supports_storage_options(strategy) -> bool:
    return not isinstance(strategy, FSDPStrategy)

When it happens

Trigger: 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).

Common situations: Shared checkpoint utility that passes storage_options for S3/GCS for all strategies; migrating from DDPStrategy where storage_options reached the TorchFilesystemCheckpointIO.

Related errors

• Could not find a FSDP model in the provided checkpoint state
• Found multiple FSDP models in the given state. Saving checkp
• Could not find a XLAFSDP model in the provided checkpoint st
• `Trainer.save_checkpoint(..., storage_options=...)` with `st
• The `{type(self).__name__}` does not use the `CheckpointIO`

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/cc72e37955163312. Report an issue: GitHub.