Lightning-AI/pytorch-lightning · error · NotImplementedError

The `{type(self).__name__}` does not use the `CheckpointIO`

Error message

The `{type(self).__name__}` does not use the `CheckpointIO` plugin interface.

What it means

FSDPStrategy manages checkpointing itself (via torch.distributed.checkpoint / FSDP state dict APIs) and does not use the CheckpointIO plugin interface. Accessing the checkpoint_io property raises NotImplementedError to signal the API is not applicable.

Source

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

        # Enables joint setup of model and optimizer, multiple optimizer param groups, and `torch.compile()`
        self._fsdp_kwargs.setdefault("use_orig_params", True)

        if device_mesh is not None:
            self._fsdp_kwargs["device_mesh"] = device_mesh

        self._activation_checkpointing_kwargs = _activation_checkpointing_kwargs(
            activation_checkpointing, activation_checkpointing_policy
        )
        self._state_dict_type = state_dict_type
        self.sharding_strategy = _init_sharding_strategy(sharding_strategy, self._fsdp_kwargs)
        self.cpu_offload = _init_cpu_offload(cpu_offload)
        self.mixed_precision = mixed_precision

    @property
    @override
    def checkpoint_io(self) -> CheckpointIO:
        raise NotImplementedError(f"The `{type(self).__name__}` does not use the `CheckpointIO` plugin interface.")

    @checkpoint_io.setter
    @override
    def checkpoint_io(self, io: CheckpointIO) -> None:
        raise NotImplementedError(f"The `{type(self).__name__}` does not support setting a `CheckpointIO` plugin.")

    @property
    @override
    def root_device(self) -> torch.device:
        assert self.parallel_devices is not None
        return self.parallel_devices[self.local_rank]

    @property
    def num_nodes(self) -> int:
        return self._num_nodes

    @num_nodes.setter
    def num_nodes(self, num_nodes: int) -> None:

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Use strategy.save_checkpoint / load_checkpoint instead of checkpoint_io methods
2. Guard with isinstance(strategy, FSDPStrategy) or hasattr checks before touching checkpoint_io
3. Update shared utilities to use the strategy-level checkpoint API

Example fix

# before
strategy.checkpoint_io.save_checkpoint(checkpoint, path)

# after
strategy.save_checkpoint(path, state)

from lightning.fabric.strategies import FSDPStrategy
if not isinstance(strategy, FSDPStrategy):
    io = strategy.checkpoint_io  # safe only here

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

try:
    strategy.checkpoint_io
except NotImplementedError:
    pass  # FSDP manages checkpointing natively

When it happens

Trigger: Reading strategy.checkpoint_io or generic code that assumes every Strategy exposes a CheckpointIO plugin (e.g. shared utilities, older Lightning code) when the strategy is FSDPStrategy.

Common situations: Porting code that called strategy.checkpoint_io.save/remove; libraries that introspect strategies; version upgrades where FSDP moved away from CheckpointIO.

Related errors

• The `{type(self).__name__}` does not support setting a `Chec
• Loading a single optimizer object from a checkpoint is not s
• Loading a single module or optimizer object from a checkpoin
• XLAFSDP only supports a single model instance with 'model' a
• `FSDPStrategy.save_checkpoint(..., storage_options=...)` is

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