{"record":{"id":"0d180b09a75fe927","repo":"Lightning-AI/pytorch-lightning","slug":"the-model-contains-a-key-full-param-name-that","errorCode":null,"errorMessage":"The model contains a key '{full_param_name}' that does not exist in the loaded checkpoint. To disable strict loading, set `strict=False`.","messagePattern":"The model contains a key '(.+?)' that does not exist in the loaded checkpoint\\. To disable strict loading, set `strict=False`\\.","errorType":"validation","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/model_parallel.py","lineNumber":581,"sourceCode":"    from torch.distributed.fsdp import FullyShardedDataParallel as FSDP\n\n    if _has_dtensor_modules(module):\n        from torch.distributed.checkpoint.state_dict import StateDictOptions, set_model_state_dict\n\n        state_dict_options = StateDictOptions(\n            broadcast_from_rank0=True,\n            full_state_dict=True,\n            # must be set False to allow loading each param separately below\n            strict=False,\n        )\n\n        for submodule_name, submodule in module.named_modules():\n            for param_name, _ in _named_parameters_and_buffers_to_load(submodule):\n                full_param_name = f\"{submodule_name}{'.' if submodule_name else ''}{param_name}\"\n                if full_param_name not in state_dict:\n                    if not strict:\n                        continue\n                    raise KeyError(\n                        f\"The model contains a key '{full_param_name}' that does not exist in the loaded checkpoint.\"\n                        \" To disable strict loading, set `strict=False`.\"\n                    )\n                local_state_dict = {param_name: state_dict[full_param_name]}\n                set_model_state_dict(submodule, local_state_dict, options=state_dict_options)\n\n    elif isinstance(module, FSDP):\n        with _get_full_state_dict_context(module, world_size=world_size, rank0_only=False):\n            module.load_state_dict(state_dict, strict=strict)\n    else:\n        module.load_state_dict(state_dict, strict=strict)\n\n\ndef _named_parameters_and_buffers_to_load(module: Module) -> Generator:\n    \"\"\"Returns parameters and buffers, with non-persistent buffers excluded.\"\"\"\n    for param_name, param in itertools.chain(\n        module.named_buffers(recurse=False),\n        module.named_parameters(recurse=False),","sourceCodeStart":563,"sourceCodeEnd":599,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/model_parallel.py#L563-L599","documentation":"With strict=True (default), _load_raw_module_state verifies every parameter/buffer name in the model exists in the loaded checkpoint state dict. A missing key — typically caused by saving from a model with different layer names (prefix mismatches, architecture changes, or a submodule added after saving) — raises this KeyError.","triggerScenarios":"Loading a checkpoint saved from a differently-named/architected model (e.g. model wrapped or renamed between save and load), loading a sharded checkpoint missing a tensor, or a key prefix like 'model.' vs '' differing between save and load.","commonSituations":"Fine-tuning from a checkpoint of a slightly different architecture; module was wrapped in a container before saving but not when loading (or vice versa); resuming after adding a new layer (new head, extra embedding).","solutions":["Align key names: wrap/unwrap the module identically at save and load time, or remap keys with a prefix-strip before loading","If missing keys are expected (new layers), pass strict=False so they keep their initialization","Inspect mismatch: sorted(set(k for _, _ in ...) ) vs state_dict keys to find the offending names","Re-save the checkpoint from the current architecture"],"exampleFix":"# before\nstrategy.load_checkpoint(path, state={'model': model})  # raises KeyError: 'model.head.weight'\n# after\nstrategy.load_checkpoint(path, state={'model': model}, strict=False)","handlingStrategy":"fallback","validationCode":"ckpt = torch.load(path, map_location='cpu')\nmissing = [n for n, _ in model.named_parameters() if n not in ckpt]\nif missing:\n    print('missing keys:', missing[:10])","typeGuard":null,"tryCatchPattern":"try:\n    strategy.load_checkpoint(path, state={'model': model})\nexcept KeyError as e:\n    if 'does not exist in the loaded checkpoint' in str(e):\n        strategy.load_checkpoint(path, state={'model': model}, strict=False)\n    else:\n        raise","preventionTips":["Use identical wrapping/naming at save and load time","Pass strict=False when fine-tuning across architecture variants"],"tags":["lightning","fabric","checkpoint","state-dict","strict-loading"],"backgroundTag":"state-dict-key-mismatch","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}