{"record":{"id":"997ab2c4867789b3","repo":"Lightning-AI/pytorch-lightning","slug":"could-not-find-a-fsdp-model-in-the-provided-checkp","errorCode":null,"errorMessage":"Could not find a FSDP model in the provided checkpoint state. Please provide the model as part of the state like so: `save_checkpoint(..., state={'model': model, ...})`. Make sure you set up the model (and optimizers if any) through the strategy before saving the checkpoint.","messagePattern":"Could not find a FSDP model in the provided checkpoint state\\. Please provide the model as part of the state like so: `save_checkpoint\\(\\.\\.\\., state=(.+?)\\)`\\. Make sure you set up the model \\(and optimizers if any\\) through the strategy before saving the checkpoint\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/fsdp.py","lineNumber":460,"sourceCode":"                \"`FSDPStrategy.save_checkpoint(..., storage_options=...)` is not supported because\"\n                \" `FSDPStrategy` does not use the `CheckpointIO`.\"\n            )\n        if filter is not None and self._state_dict_type == \"sharded\":\n            # https://github.com/pytorch/pytorch/issues/105379\n            raise NotImplementedError(\n                \"FSDP doesn't support loading sharded filtered checkpoints, so saving them is disabled.\"\n            )\n\n        # broadcast the path from rank 0 to ensure all the states are saved in a common path\n        path = _resolve_path(self.broadcast(path))\n        if self._state_dict_type == \"full\" and _is_checkpoint_dir(path) and not _is_sharded_checkpoint(path):\n            raise IsADirectoryError(f\"The checkpoint path exists and is a directory: {path}\")\n\n        from torch.distributed.fsdp import FullyShardedDataParallel as FSDP\n\n        modules = [module for module in state.values() if _has_fsdp_modules(module)]\n        if len(modules) == 0:\n            raise ValueError(\n                \"Could not find a FSDP model in the provided checkpoint state. Please provide the model as\"\n                \" part of the state like so: `save_checkpoint(..., state={'model': model, ...})`. Make sure\"\n                \" you set up the model (and optimizers if any) through the strategy before saving the checkpoint.\"\n            )\n        if len(modules) > 1:\n            raise ValueError(\n                \"Found multiple FSDP models in the given state. Saving checkpoints with FSDP is\"\n                \" currently limited to a single model per checkpoint. To save multiple models, call the\"\n                \" save method for each model separately with a different path.\"\n            )\n        module = modules[0]\n\n        if self._state_dict_type == \"sharded\":\n            _prepare_directory_checkpoint(path)\n\n            state_dict_ctx = _get_sharded_state_dict_context(module)\n\n            # replace the modules and optimizer objects in the state with their local state dict","sourceCodeStart":442,"sourceCodeEnd":478,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/fsdp.py#L442-L478","documentation":"FSDP save_checkpoint requires at least one FSDP-wrapped module in the state dict so it knows what to shard/gather. If no value in state contains FSDP modules (nothing was set up through the strategy), ValueError is raised with guidance on the expected state format.","triggerScenarios":"strategy.save_checkpoint(path, state={'step': 10, 'loss': 0.5}) with no model entry; or saving the raw model that was never passed through fabric.setup/setup_module (so it is not FSDP-wrapped).","commonSituations":"Saving metadata-only checkpoints; keeping a reference to the unwrapped model in state instead of the wrapped one returned by setup; calling strategy.save_checkpoint instead of fabric.save_checkpoint before setup.","solutions":["Include the set-up model: state = {'model': model, ...} using the module returned by fabric.setup/setup_module","Call fabric.setup(model, optimizer) before saving so the model is FSDP-wrapped","Use fabric.save_checkpoint(path, state) which routes through the same requirement"],"exampleFix":"# before\nstrategy.save_checkpoint(path, {\"step\": step, \"raw_model\": raw_model})\n\n# after\nmodel, optimizer = fabric.setup(model, optimizer)\nstrategy.save_checkpoint(path, {\"model\": model, \"optimizer\": optimizer, \"step\": step})","handlingStrategy":"validation","validationCode":"from torch.distributed.fsdp import FullyShardedDataParallel\nassert any(\n    isinstance(v, FullyShardedDataParallel) or any(isinstance(m, FullyShardedDataParallel) for m in getattr(v, \"modules\", lambda: [])())\n    for v in state.values()\n), \"state must contain the FSDP-wrapped model under some key\"","typeGuard":"from torch.distributed.fsdp import FullyShardedDataParallel\ndef state_has_fsdp(state: dict) -> bool:\n    for v in state.values():\n        if isinstance(v, FullyShardedDataParallel):\n            return True\n        if hasattr(v, \"modules\"):\n            if any(isinstance(m, FullyShardedDataParallel) for m in v.modules()):\n                return True\n    return False","tryCatchPattern":null,"preventionTips":["Standardize on state={'model': model, ...} for saves","Always save the wrapped module returned by fabric.setup","Route saves through fabric.save_checkpoint"],"tags":["fsdp","checkpoint","state","save"],"backgroundTag":"checkpoint-state-missing-model","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}