Lightning-AI/pytorch-lightning · error · ValueError

Got FSDPStrategy.load_checkpoint(..., state={state!r}) but a

Error message

Got FSDPStrategy.load_checkpoint(..., state={state!r}) but a state with at least  a model instance to reload is required. Pass it in like so: FSDPStrategy.load_checkpoint(..., state={'model': model, ...})

What it means

FSDPStrategy.load_checkpoint requires the caller to pass a state containing at least one model instance so it knows which module to load the sharded weights into. Passing None, an empty dict, or a falsy state is rejected up front.

Source

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

                        converted = obj.state_dict() if isinstance(obj, _Stateful) else obj
                    _apply_filter(key, filter or {}, converted, full_state)

            if self.global_rank == 0:
                _atomic_save(full_state, path)
        else:
            raise ValueError(f"Unknown state_dict_type: {self._state_dict_type}")

    @override
    def load_checkpoint(
        self,
        path: _PATH,
        state: Optional[Union[Module, Optimizer, dict[str, Union[Module, Optimizer, Any]]]] = None,
        strict: bool = True,
        weights_only: Optional[bool] = None,
    ) -> dict[str, Any]:
        """Load the contents from a checkpoint and restore the state of the given objects."""
        if not state:
            raise ValueError(
                f"Got FSDPStrategy.load_checkpoint(..., state={state!r}) but a state with at least "
                f" a model instance to reload is required. Pass it in like so:"
                " FSDPStrategy.load_checkpoint(..., state={'model': model, ...})"
            )
        # broadcast the path from rank 0 to ensure all the states are loaded from a common path
        path = _resolve_path(self.broadcast(path))

        if isinstance(state, Module):
            from lightning.fabric.strategies.model_parallel import _load_raw_module_state_from_path

            _load_raw_module_state_from_path(path, module=state, world_size=self.world_size, strict=strict)
            return {}

        if isinstance(state, Optimizer):
            raise NotImplementedError(
                "Loading a single optimizer object from a checkpoint is not supported yet with the FSDP strategy."
            )

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pass the model: load_checkpoint(path, {'model': model, 'optimizer': optimizer})
2. Ensure the model was set up through the strategy (fabric.setup(module)) before loading
3. If you only want raw weights, use the single-module form load_checkpoint(path, module)

Example fix

# before
state = strategy.load_checkpoint(path)
model = state['model']
# after
strategy.load_checkpoint(path, state={'model': model, 'optimizer': optimizer})

if not state or not any(hasattr(v, 'load_state_dict') for v in state.values()):
    raise ValueError('state must contain the model to load into')

def has_loadable_model(state) -> bool:
    return bool(state) and any(hasattr(v, 'load_state_dict') for v in state.values())

When it happens

Trigger: Calling fsdp_strategy.load_checkpoint(path) with no state argument, or load_checkpoint(path, {}) or load_checkpoint(path, None).

Common situations: Assuming load_checkpoint returns a fully constructed model (as some checkpoint utilities do); adapting code from a strategy whose load_checkpoint accepts state=None; forgetting to pass the model after refactoring a training script.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Could not find a FSDP model in the provided checkpoint state
• Found multiple FSDP models in the given state. Loading check
• Found multiple FSDP models in the given state. Saving checkp
• Loading a single optimizer object from a checkpoint is not s
• The path {str(path)!r} does not point to a valid checkpoint.

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