invoke-ai/InvokeAI · error · ValueError

PiD decoder backbone {backbone!r} is not supported. Expected

Error message

PiD decoder backbone {backbone!r} is not supported. Expected one of: {list(_PER_BACKBONE.keys())}.

What it means

build_pid_net constructs an uninitialized PidNet sized for a named backbone, looking up per-backbone hyperparameters in _PER_BACKBONE. If the backbone name is not a key of that registry, it raises ValueError listing the supported names. This is a decode-time configuration error: the requested decoder architecture is unknown to this version of the library.

Source

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

    patch_tokens = batch_size * (out_h // patch_size) * (out_w // patch_size)
    if patch_tokens <= _PID_ACTIVATION_CHUNK_SIZE:
        # The pixel blocks take the unchunked path at and below the threshold.
        return unoptimized
    chunked = int(output_bytes * _PID_DECODE_CHUNKED_SCALING_CONSTANT + _PID_DECODE_CHUNKED_FIXED_BYTES)
    # The fixed term makes the calibrated chunked formula temporarily greater than the unoptimized
    # formula just after chunking engages. Keep the unoptimized estimate until the formulas cross;
    # after that point the chunked estimate is the lower (optimized) reservation.
    return min(chunked, unoptimized)


def build_pid_net(backbone: BaseModelType) -> PidNet:
    """Build an uninitialised PidNet of the right shape for *backbone*.

    The returned network is on CPU and in float32; the caller is responsible
    for casting it to the desired dtype/device before loading weights.
    """
    if backbone not in _PER_BACKBONE:
        raise ValueError(
            f"PiD decoder backbone {backbone!r} is not supported. Expected one of: {list(_PER_BACKBONE.keys())}."
        )
    kwargs = {**_PID_SR4X_BASE, **_PER_BACKBONE[backbone]}
    return PidNet(**kwargs)


# The one PidNet parameter whose shape depends on the backbone: a Conv2d whose in-channels are the
# backbone's latent channel count (4 SDXL / 16 FLUX.1, SD3, Qwen-Image / 128 FLUX.2). Every other
# parameter is name- and shape-identical across all five, which is what lets model identification
# hold a checkpoint to one contract before it knows which backbone the checkpoint is for.
BACKBONE_DISCRIMINATOR_KEY = "lq_proj.latent_proj.0.weight"

# The backbone the contract is probed from. Any of the five would do — see the docstring below.
_KEY_CONTRACT_BACKBONE = BaseModelType.Flux


@lru_cache(maxsize=None)
def required_pid_net_shapes(backbone: BaseModelType = _KEY_CONTRACT_BACKBONE) -> Mapping[str, tuple[int, ...]]:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Use one of the supported names printed in the message (the keys of _PER_BACKBONE)
2. Fix typos/casing in the backbone field of the model config or loader call
3. Upgrade the library if the backbone was added in a newer release

Example fix

// before
net = build_pid_net("pid_xll")
// after
net = build_pid_net("pid_xl")  # must be a key of _PER_BACKBONE

from invokeai.backend.pid.decode import _PER_BACKBONE
assert backbone in _PER_BACKBONE, f"{backbone!r} not in {list(_PER_BACKBONE)}"

try:
    net = load_pid_decoder(path, backbone=backbone)
except ValueError as e:
    if "not supported" in str(e):
        logger.error(f"Bad backbone: {e}")
    raise

When it happens

Trigger: Calling build_pid_net(backbone=...) (also reached via required_pid_net_shapes / load_pid_decoder) with a misspelled, renamed, or not-yet-supported backbone identifier.

Common situations: Typo in a model config's backbone field, checkpoint metadata referencing a backbone from a newer/older library version, or a case mismatch (e.g. 'xl' vs 'XL').

Related errors

• LoRA '{lora.lora.key}' has conflicting weights on the transf
• Model '{main_config.name}' is not a Krea-2 main model. Selec
• ed_hidden_size {self.ed_hidden_size} must be divisible by ed
• Admin privileges required
• Expected LlavaOnevisionForConditionalGeneration, got {type(m

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