invoke-ai/InvokeAI · error · ValueError

Unrecognised PiD decoder checkpoint extension: {suffix!r}

Error message

Unrecognised PiD decoder checkpoint extension: {suffix!r}

What it means

_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.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/pid_decoder.py:36

from invokeai.backend.model_manager.load.load_default import ModelLoader
from invokeai.backend.model_manager.load.model_loader_registry import ModelLoaderRegistry
from invokeai.backend.model_manager.taxonomy import AnyModel, BaseModelType, ModelFormat, ModelType, SubModelType
from invokeai.backend.pid.decode import load_pid_decoder
from invokeai.backend.pid.state_dict_utils import strip_net_prefix


def _load_raw_checkpoint(path: Path) -> dict[str, torch.Tensor]:
    suffix = path.suffix.lower()
    if suffix == ".safetensors":
        return safetensors_load_file(str(path))
    if suffix in {".pth", ".pt", ".ckpt", ".bin"}:
        # NVIDIA's PiD `.pth` checkpoints are plain tensor dicts (verified
        # against the released res2k_sr4x_official_flux checkpoint).
        sd = torch.load(str(path), map_location="cpu", weights_only=True)
        if isinstance(sd, dict) and "state_dict" in sd and isinstance(sd["state_dict"], dict):
            sd = sd["state_dict"]
        return sd  # type: ignore[return-value]
    raise ValueError(f"Unrecognised PiD decoder checkpoint extension: {suffix!r}")


@ModelLoaderRegistry.register(base=BaseModelType.Flux, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)
@ModelLoaderRegistry.register(base=BaseModelType.Flux2, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)
@ModelLoaderRegistry.register(
    base=BaseModelType.StableDiffusion3, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint
)
@ModelLoaderRegistry.register(
    base=BaseModelType.StableDiffusionXL, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint
)
@ModelLoaderRegistry.register(base=BaseModelType.QwenImage, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)
class PiDDecoderLoader(ModelLoader):
    """Loads a PiD checkpoint into a fully-constructed PidNet of the matching backbone."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,

View on GitHub (pinned to 0b6a024f2f)

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).

Example fix

// before
path = "pid_decoder.gguf"           # ValueError: Unrecognised ... '.gguf'
// after
path = "pid_decoder.safetensors"    # or .pth/.pt/.ckpt/.bin

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

SUPPORTED = {".safetensors", ".pth", ".pt", ".ckpt", ".bin"}
p = Path(model_path)
if p.suffix.lower() not in SUPPORTED:
    raise ValueError(f"convert {p.suffix!r} to a supported PiD checkpoint format first")

Try / catch

try:
    pid = loader._load_model(cfg)
except ValueError as e:
    if "Unrecognised PiD decoder checkpoint extension" in str(e):
        convert_to_safetensors(Path(cfg.path))  # re-export then reload
        pid = loader._load_model(cfg)
    else:
        raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/b00bdd8b675b8d63. Report an issue: GitHub.