Lightning-AI/pytorch-lightning · error · TypeError

`{type(self).__name__}.save_checkpoint(..., storage_options=

Error message

`{type(self).__name__}.save_checkpoint(..., storage_options=...)` is not supported because `{type(self).__name__}` does not use the `CheckpointIO`.

What it means

ModelParallelStrategy.save_checkpoint does not go through the CheckpointIO plugin, so it cannot honor the storage_options argument (which is a CheckpointIO/fsspec concept). Passing storage_options raises TypeError.

Source

Thrown at src/lightning/pytorch/strategies/model_parallel.py:306

        assert self.model is not None

        state_dict = get_optimizer_state_dict(self.model, optimizer, options=state_dict_options)
        if not self._save_distributed_checkpoint and self.global_rank == 0:
            state_dict = _align_compiled_param_names_with_module(state_dict, self.model)
            state_dict = FSDP.rekey_optim_state_dict(state_dict, OptimStateKeyType.PARAM_ID, self.model)
        return state_dict

    @override
    def load_optimizer_state_dict(self, checkpoint: Mapping[str, Any]) -> None:
        # Override to do nothing, the strategy already loaded the states in `load_checkpoint()`
        pass

    @override
    def save_checkpoint(
        self, checkpoint: dict[str, Any], filepath: _PATH, storage_options: Optional[Any] = None
    ) -> None:
        if storage_options is not None:
            raise TypeError(
                f"`{type(self).__name__}.save_checkpoint(..., storage_options=...)` is not supported because"
                f" `{type(self).__name__}` does not use the `CheckpointIO`."
            )
        # broadcast the path from rank 0 to ensure all the checkpoints are saved to a common path
        path = _resolve_path(self.broadcast(filepath))
        if _is_checkpoint_dir(path) and not self._save_distributed_checkpoint and not _is_sharded_checkpoint(path):
            raise IsADirectoryError(f"The checkpoint path exists and is a directory: {path}")

        if self._save_distributed_checkpoint:
            _prepare_directory_checkpoint(path)

            converted_state = {"state_dict": checkpoint.pop("state_dict")}
            converted_state.update({
                f"optimizer_{idx}": optim_state
                for idx, optim_state in enumerate(checkpoint.pop("optimizer_states", []))
            })
            _distributed_checkpoint_save(converted_state, path)

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Drop the storage_options argument when using ModelParallelStrategy
2. Configure storage credentials via environment variables (AWS_*, etc.) so fsspec picks them up implicitly when the checkpoint layer reads/writes the path
3. If you need storage_options, use a strategy whose CheckpointIO supports them

Example fix

# before
trainer.save_checkpoint("s3://bucket/ckpt", storage_options={"key": ...})

# after
os.environ.setdefault("AWS_...")
trainer.save_checkpoint("s3://bucket/ckpt")

if isinstance(strategy, ModelParallelStrategy):
    assert storage_options is None, "ModelParallelStrategy does not support storage_options"

When it happens

Trigger: Calling strategy.save_checkpoint(ckpt, path, storage_options={...}) or trainer.save_checkpoint(..., storage_options=...) with ModelParallelStrategy; usually when code written for cloud-storage checkpointing (fsspec URLs, options) is reused with this strategy.

Common situations: Shared checkpoint utilities that pass storage_options for S3/GCS; migrating from strategies that support it (e.g. DeepSpeed via CheckpointIO).

Related errors

• `Trainer.save_checkpoint(..., storage_options=...)` with `st
• `FSDPStrategy.save_checkpoint(..., storage_options=...)` is
• Could not find a distributed model in the provided checkpoin
• Found multiple distributed models in the given state. Loadin
• The checkpoint path exists and is a directory: {path}

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