What causes "Unsupported PiD backbone: {backbone!r}" in invoke-ai/InvokeAI?

Use BaseModelType.Flux (or another type present in _PER_BACKBONE) as the backbone argument

invoke-ai/InvokeAI · error · ValueError

Unsupported PiD backbone: {backbone!r}

Error message

Unsupported PiD backbone: {backbone!r}

What it means

PiDDecoder supports only a fixed set of backbones (per-backbone configs live in the module-level _PER_BACKBONE map). __init__ validates the backbone BaseModelType argument and raises ValueError for anything not registered, e.g. unsupported or newly added model families.

Source

Thrown at invokeai/backend/pid/decode.py:466

    seed: int = 0
    pid_memory_optimization: bool = False
    student_t_list: list[float] = field(default_factory=lambda: list(_STUDENT_T_LIST))


class PiDDecoder:
    """High-level decoder that hides PidNet construction and sampling.

    Usage::

        net = load_pid_decoder(state_dict, backbone)
        net = net.to(device=..., dtype=...)
        decoder = PiDDecoder(net, backbone=BaseModelType.Flux)
        image = decoder.decode(latent=..., caption_embs=...)
    """

    def __init__(self, net: PidNet, backbone: BaseModelType) -> None:
        if backbone not in _PER_BACKBONE:
            raise ValueError(f"Unsupported PiD backbone: {backbone!r}")
        self.net = net
        self.backbone = backbone

    @property
    def sr_scale(self) -> int:
        return int(self.net.sr_scale)

    @property
    def latent_spatial_down_factor(self) -> int:
        return int(_PER_BACKBONE[self.backbone]["latent_spatial_down_factor"])

    @torch.no_grad()
    def decode(
        self,
        *,
        latent: Tensor,
        caption_embs: Tensor,
        caption_mask: Optional[Tensor] = None,

View on GitHub (pinned to 0b6a024f2f)

Solutions

Use BaseModelType.Flux (or another type present in _PER_BACKBONE) as the backbone argument
Check _PER_BACKBONE keys in invokeai/backend/pid/decode.py for the supported set
If you need a new backbone, add its config entry to _PER_BACKBONE before passing it

Example fix

// before
decoder = PiDDecoder(net, backbone=BaseModelType.SDXL)
// after
decoder = PiDDecoder(net, backbone=BaseModelType.Flux)

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.util.base_types import BaseModelType
from invokeai.backend.pid.decode import _PER_BACKBONE
assert backbone in _PER_BACKBONE, f"backbone {backbone} unsupported"
decoder = PiDDecoder(net, backbone=backbone)

Type guard

def is_supported_pid_backbone(b: BaseModelType) -> bool:
    return b in _PER_BACKBONE

Try / catch

try:
    decoder = PiDDecoder(net, backbone=backbone)
except ValueError as e:
    logger.error(str(e))
    decoder = None  # or fall back to a supported backbone

Prevention

Only pass BaseModelType values enumerated in _PER_BACKBONE
Centralize backbone selection in config so it cannot be arbitrary
Add a unit test asserting each supported base constructs a decoder

When it happens

Trigger: Constructing PiDDecoder(net, backbone=<BaseModelType not in _PER_BACKBONE>) — e.g. passing BaseModelType.SDXL, StableDiffusion3, or a placeholder/unknown enum value instead of Flux.

Common situations: Wiring a PiD decoder node to a non-FLUX base model; typo or stale config mapping a model's base type to PiD; using a new InvokeAI base model type before PiD support exists.

Related errors

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