{"record":{"id":"ad77c966497fbbf1","repo":"invoke-ai/InvokeAI","slug":"pid-checkpoint-has-a-malformed-latent-proj-expect","errorCode":null,"errorMessage":"PiD checkpoint has a malformed latent_proj: expected a 4D conv weight with a 1x1 kernel, got {shape if shape is not None else 'a value with no shape'}","messagePattern":"PiD checkpoint has a malformed latent_proj: expected a 4D conv weight with a 1x1 kernel, got (.+?)","errorType":"exception","errorClass":"InvalidMatchError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/configs/pid_decoder.py","lineNumber":85,"sourceCode":"# `.pth` is free to supply keys that are not strings (see `strip_net_prefix`).\n_Shapes = Mapping[Any, tuple[int, ...] | None]\n\n\ndef _raise_if_discriminator_malformed(shapes: _Shapes, contract: Mapping[str, tuple[int, ...]]) -> None:\n    \"\"\"Reject a checkpoint whose latent projection is present but is not a conv weight.\n\n    Every read identification makes off this weight requires it to be a 4D conv, and each used to\n    answer None when it was not — so a malformed tensor made the architecture check, the backbone\n    check and the channel check all abstain at once, and the file fell through to name-only matching,\n    which happily accepted it. Loading then failed on a size mismatch.\n\n    Only reached when the weight is present: its *absence* is a truncation, which\n    `_raise_if_pid_net_contract_unmet` diagnoses far better than a guess about the architecture.\n    \"\"\"\n    shape = shapes[_LATENT_PROJ_KEY]\n    expected = contract[_LATENT_PROJ_KEY]\n    if shape is None or len(shape) != len(expected) or shape[2:] != expected[2:]:\n        raise InvalidMatchError(\n            f\"PiD checkpoint has a malformed {_LATENT_PROJ_KEY}: expected a \"\n            f\"{len(expected)}D conv weight with a {'x'.join(str(d) for d in expected[2:])} kernel, got \"\n            f\"{shape if shape is not None else 'a value with no shape'}\"\n        )\n\n\ndef _raise_if_architecture_unsupported(shapes: _Shapes) -> None:\n    \"\"\"Reject a PiD decoder whose network shape `build_pid_net` cannot construct.\n\n    Runs before the contract check so the diagnosis is the accurate one: a v1.5 checkpoint is intact,\n    and judging it against the legacy contract would report it as a pile of missing and unexpected\n    keys rather than as the newer architecture it is.\n    \"\"\"\n    lq_hidden_dim = shapes[_LATENT_PROJ_KEY][0]  # type: ignore[index]  # rank checked above\n    if lq_hidden_dim != _SUPPORTED_LQ_HIDDEN_DIM:\n        raise InvalidMatchError(\n            f\"PiD decoder has lq_proj hidden dim {lq_hidden_dim}, but InvokeAI only supports the legacy \"\n            f\"{_SUPPORTED_LQ_HIDDEN_DIM}-dim architecture (NVIDIA's v1.5 checkpoints are not yet supported).\"","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/configs/pid_decoder.py#L67-L103","documentation":"InvalidMatchError from _raise_if_discriminator_malformed (called during PiDDecoder_Checkpoint_Config_Base.from_model_on_disk): the checkpoint contains the key lq_proj.latent_proj.0.weight, but its shape is None, has the wrong rank, or its spatial kernel does not match the expected conv kernel from the contract (a 4D conv weight). This weight encodes both the architecture version (dim 0) and the backbone latent channels (dim 1), so a malformed tensor means the file cannot be identified or loaded reliably — and skipping the check would silently fall through to name-only matching followed by a load-time size mismatch.","triggerScenarios":"Importing a truncated/corrupted NVIDIA PiD .pth checkpoint where the lq_proj tensor was written incompletely (shape lost or wrong); loading a PiD-like checkpoint from a modified/converted pipeline where latent_proj was replaced by a non-conv module (different rank or kernel); an unrelated tensor stored under a key containing 'lq_proj'.","commonSituations":"Interrupted HuggingFace downloads of nvidia/PiD res2k* checkpoints; repacking tools that rewrite conv layers (fused/replaced projections) before export; older PiD versions with a different latent_proj layout.","solutions":["Re-download the checkpoint from https://huggingface.co/nvidia/PiD and retry — corruption/truncation is the most common cause","Verify the file is an official PiD release for your backbone (FLUX.1, FLUX.2, SD3, SDXL, Qwen-Image) rather than a modified export; unmodified official weights carry the 4D conv latent_proj","Inspect the tensor (torch.load and print the shape of the lq_proj.latent_proj.0.weight tensor) to confirm rank/kernel before reporting; a v1.5 checkpoint instead triggers the 512-dim architecture error"],"exampleFix":"// before\n# importing a partially-downloaded PiD checkpoint:\n# shapes[\"lq_proj.latent_proj.0.weight\"] -> None\n// after\n# huggingface-cli download nvidia/PiD res2k_sr4x_flux.pth --local-dir .  # fresh copy\n# re-run model import with the verified file","handlingStrategy":"validation","validationCode":"import torch\nsd = torch.load(pid_pth, map_location='cpu')\nw = next(v for k, v in sd.items() if 'lq_proj.latent_proj.0.weight' in str(k))\nassert w.dim() == 4 and w.shape[2:] == (3, 3), f'latent_proj malformed: {tuple(w.shape)}'","typeGuard":"def has_wellformed_latent_proj(shapes: dict) -> bool:\n    s = shapes.get('lq_proj.latent_proj.0.weight')\n    return s is not None and len(s) == 4 and tuple(s[2:]) == (3, 3)","tryCatchPattern":"try:\n    import_model(pid_pth)\nexcept InvalidMatchError as e:\n    if 'malformed' in str(e) and 'latent_proj' in str(e):\n        print(f'{pid_pth.name} is corrupt or modified — re-download from nvidia/PiD')\n    else:\n        raise","preventionTips":["Verify download size/hash against the nvidia/PiD repo before importing","Avoid repack/convert tools that rewrite conv layers in PiD checkpoints","Import only official backbone presets (res2k*, res2kto4k*) — not modified exports","Run torch.load and inspect the lq_proj weight shape when a PiD file is suspect"],"tags":["model-manager","pid-decoder","checkpoint-corruption","state-dict"],"backgroundTag":"checkpoint-tensor-shape-mismatch","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}