{"record":{"id":"b00bdd8b675b8d63","repo":"invoke-ai/InvokeAI","slug":"unrecognised-pid-decoder-checkpoint-extension-su","errorCode":null,"errorMessage":"Unrecognised PiD decoder checkpoint extension: {suffix!r}","messagePattern":"Unrecognised PiD decoder checkpoint extension: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/pid_decoder.py","lineNumber":36,"sourceCode":"from invokeai.backend.model_manager.load.load_default import ModelLoader\nfrom invokeai.backend.model_manager.load.model_loader_registry import ModelLoaderRegistry\nfrom invokeai.backend.model_manager.taxonomy import AnyModel, BaseModelType, ModelFormat, ModelType, SubModelType\nfrom invokeai.backend.pid.decode import load_pid_decoder\nfrom invokeai.backend.pid.state_dict_utils import strip_net_prefix\n\n\ndef _load_raw_checkpoint(path: Path) -> dict[str, torch.Tensor]:\n    suffix = path.suffix.lower()\n    if suffix == \".safetensors\":\n        return safetensors_load_file(str(path))\n    if suffix in {\".pth\", \".pt\", \".ckpt\", \".bin\"}:\n        # NVIDIA's PiD `.pth` checkpoints are plain tensor dicts (verified\n        # against the released res2k_sr4x_official_flux checkpoint).\n        sd = torch.load(str(path), map_location=\"cpu\", weights_only=True)\n        if isinstance(sd, dict) and \"state_dict\" in sd and isinstance(sd[\"state_dict\"], dict):\n            sd = sd[\"state_dict\"]\n        return sd  # type: ignore[return-value]\n    raise ValueError(f\"Unrecognised PiD decoder checkpoint extension: {suffix!r}\")\n\n\n@ModelLoaderRegistry.register(base=BaseModelType.Flux, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)\n@ModelLoaderRegistry.register(base=BaseModelType.Flux2, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)\n@ModelLoaderRegistry.register(\n    base=BaseModelType.StableDiffusion3, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint\n)\n@ModelLoaderRegistry.register(\n    base=BaseModelType.StableDiffusionXL, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint\n)\n@ModelLoaderRegistry.register(base=BaseModelType.QwenImage, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)\nclass PiDDecoderLoader(ModelLoader):\n    \"\"\"Loads a PiD checkpoint into a fully-constructed PidNet of the matching backbone.\"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/pid_decoder.py#L18-L54","documentation":"_load_raw_checkpoint dispatches on the checkpoint file's extension: .safetensors via safetensors, and .pth/.pt/.ckpt/.bin via torch.load. Any other suffix (e.g. .gguf, .onnx, .safetensor typo, no extension) raises a ValueError with the offending suffix. The loader expects the user to add a PiD decoder checkpoint in one of the supported container formats.","triggerScenarios":"Adding a PiD decoder model whose path ends in an unsupported extension — a .gguf quantization, a .tar/.zip archive, a mistyped '.safetensor' (missing 's'), an uppercase variant is fine (lowered), but an extensionless file or '.bin.gz' will trip this.","commonSituations":"Downloading a quantized or packaged PiD checkpoint that InvokeAI doesn't unpack; renaming files and dropping or altering the extension; pointing the model record at a directory-adjacent metadata file instead of the weights.","solutions":["Convert or re-export the checkpoint to .safetensors (safetensors.torch.save_file) or one of .pth/.pt/.ckpt/.bin.","Fix the file path/extension in the model record if it's a typo (e.g. .safetensor -> .safetensors).","Download the original NVIDIA PiD checkpoint in .pth form for the matching backbone.","Verify Path(config.path).suffix is the weights file, not an archive or index (e.g. .index.json)."],"exampleFix":"// before\npath = \"pid_decoder.gguf\"           # ValueError: Unrecognised ... '.gguf'\n// after\npath = \"pid_decoder.safetensors\"    # or .pth/.pt/.ckpt/.bin","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nSUPPORTED = {\".safetensors\", \".pth\", \".pt\", \".ckpt\", \".bin\"}\np = Path(model_path)\nif p.suffix.lower() not in SUPPORTED:\n    raise ValueError(f\"convert {p.suffix!r} to a supported PiD checkpoint format first\")","typeGuard":null,"tryCatchPattern":"try:\n    pid = loader._load_model(cfg)\nexcept ValueError as e:\n    if \"Unrecognised PiD decoder checkpoint extension\" in str(e):\n        convert_to_safetensors(Path(cfg.path))  # re-export then reload\n        pid = loader._load_model(cfg)\n    else:\n        raise","preventionTips":["Check the file extension before adding a PiD decoder model.","Convert GGUF/zip/tar packaged decoders to safetensors or pth first.","Confirm the recorded path points at the weights file, not an index or archive."],"tags":["python","checkpoint","file-format","model-loading","invokeai"],"backgroundTag":"unsupported-checkpoint-extension","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}