Lightning-AI/pytorch-lightning · error · ValueError

Unknown state_dict_type: {self._state_dict_type}

Error message

Unknown state_dict_type: {self._state_dict_type}

What it means

FSDPStrategy supports three _state_dict_type modes ('full', 'sharded', 'sharded_state_dict'); the value being used matches none of them. This is an internal invariant break, normally only reachable if the private attribute _state_dict_type was mutated to an unexpected string or an outdated/renamed value.

Source

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

            if _is_sharded_checkpoint(path):
                _remove_checkpoint(path)

            state_dict_ctx = _get_full_state_dict_context(module, world_size=self.world_size)
            full_state: dict[str, Any] = {}
            with state_dict_ctx:
                for key, obj in state.items():
                    if isinstance(obj, Module):
                        converted = obj.state_dict()
                    elif isinstance(obj, Optimizer):
                        converted = FSDP.optim_state_dict(module, obj)
                    else:  # everything not a module or optimizer is considered metadata
                        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))

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pass one of the supported values: 'full', 'sharded', or 'sharded_state_dict'
2. Remove code that writes to _state_dict_type directly and use the public constructor argument
3. Align Lightning version with the code that produced the value

Example fix

# before
strategy._state_dict_type = 'local'
# after
strategy = FSDPStrategy(state_dict_type='sharded')

VALID = {'full', 'sharded', 'sharded_state_dict'}
assert strategy._state_dict_type in VALID, f'bad state_dict_type: {strategy._state_dict_type}'

def is_valid_state_dict_type(v: str) -> bool:
    return v in {'full', 'sharded', 'sharded_state_dict'}

When it happens

Trigger: Setting strategy._state_dict_type manually (e.g. 'local') before calling save_checkpoint, or constructing FSDPStrategy with an invalid state_dict_type argument in a version where the accepted set changed.

Common situations: Copy-pasted code from another Lightning version; monkeypatching internals; typo in the string ('sharded_state_dict_' etc.).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The optimizer has references to the model's meta-device para
• `precision={precision!r})` is not supported in FSDP. `precis
• `precision={precision!r}` does not use a scaler, found {scal
• Gradient clipping is not implemented for optimizers handling
• Found multiple FSDP models in the given state. Saving checkp

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