invoke-ai/InvokeAI · error · ValueError

{node_title} requires a {node_base.value} PiD decoder, but t

Error message

{node_title} requires a {node_base.value} PiD decoder, but the selected decoder is configured for {decoder_base.value}. Connect a PiD decoder whose base matches this node.

What it means

assert_pid_decoder_matches_base enforces that the PiD decoder's backbone base matches the consuming node's required base. Some nodes (e.g. Z-Image decode) deliberately accept FLUX decoders; otherwise the bases must match exactly, otherwise ValueError is raised.

Source

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

    caption_mask = toks.attention_mask[:, select_idx].to(torch.bool)
    return caption_embs, caption_mask


def assert_pid_decoder_matches_base(decoder_base: BaseModelType, node_base: BaseModelType, *, node_title: str) -> None:
    """Guard a base-specific PiD decode node against an incompatible decoder.

    The generic ``pid_decoder_loader`` exposes every PiD decoder through one base-agnostic
    field, so in the Nodes editor a decoder for the wrong backbone can be connected to a
    decode node. The decoders share tensor names across backbones, so a mismatch would either
    silently produce garbage (compatible shapes) or fail deep inside inference (incompatible
    shapes). Validate up front instead.

    ``node_base`` is the backbone the node feeds to ``PidNet`` — e.g. the Z-Image decode node
    reuses the FLUX decoder and therefore passes ``BaseModelType.Flux`` here, so a FLUX decoder
    is accepted for Z-Image while every other pairing must match exactly.
    """
    if decoder_base != node_base:
        raise ValueError(
            f"{node_title} requires a {node_base.value} PiD decoder, but the selected decoder is "
            f"configured for {decoder_base.value}. Connect a PiD decoder whose base matches this node."
        )


__all__ = [
    "BACKBONE_DISCRIMINATOR_KEY",
    "PID_CHI_PROMPT",
    "PID_MODEL_MAX_LENGTH",
    "PID_NEGATIVE_PROMPT",
    "PiDDecodeConfig",
    "PiDDecoder",
    "assert_pid_decoder_matches_base",
    "build_pid_net",
    "encode_caption_for_pid",
    "load_pid_decoder",
    "required_pid_net_shapes",
]

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Connect a PiD decoder model whose configured base matches the node's requirement (FLUX decoders also satisfy Z-Image nodes)
2. Check the decoder's base model metadata and re-select/download the correct variant
3. Update the node's declared base only if the decoder genuinely supports it

Example fix

// before
assert_pid_decoder_matches_base(decoder_base=BaseModelType.SDXL, node_base=BaseModelType.ZImage, node_title="Z-Image Decode")
// after
assert_pid_decoder_matches_base(decoder_base=BaseModelType.Flux, node_base=BaseModelType.ZImage, node_title="Z-Image Decode")

from invokeai.backend.util.base_types import BaseModelType
decoder_base = pid_decoder.backbone
allowed = {node_base, BaseModelType.Flux} if node_is_z_image else {node_base}
assert decoder_base in allowed, f"decoder base {decoder_base} unusable for {node_title}"

def decoder_matches_node(decoder, node_base: BaseModelType) -> bool:
    if decoder.backbone == node_base:
        return True
    return node_base == BaseModelType.ZImage and decoder.backbone == BaseModelType.Flux

try:
    assert_pid_decoder_matches_base(decoder_base, node_base, node_title)
except ValueError as e:
    raise RuntimeError(f"Workflow misconfigured: {e}") from e

When it happens

Trigger: Connecting a PiD decoder whose decoder_base differs from node_base in a node's invoke() — e.g. a Z-Image node wired to an SDXL-configured decoder, or any node receiving a decoder built with a mismatched BaseModelType.

Common situations: Selecting the wrong PiD decoder model in the workflow UI; a decoder saved under one base and reused for another; copy-pasting workflows after switching base models.

Related errors

• '${field_name}' is not a call_saved_workflow dynamic input f
• Invalid call_saved_workflow dynamic input field '${field_nam
• Invalid or expired token
• User not found or inactive
• Missing authentication credentials

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