invoke-ai/InvokeAI · error · KeyError

Unknown (backbone, ckpt_type)=({backbone!r}, {ckpt_type!r}).

Error message

Unknown (backbone, ckpt_type)=({backbone!r}, {ckpt_type!r}). Valid: {valid}

What it means

get_pid_checkpoint looks up PID_CHECKPOINT_REGISTRY[(backbone, ckpt_type)]. When the pair is not in the registry (typically asking for a '2kto4k' variant of a backbone like rae or scale_rae that doesn't ship one), a KeyError is raised listing all valid backbone+type combinations.

Source

Thrown at invokeai/backend/pid/_src/inference/checkpoint_registry.py:114

PID_CHECKPOINT_REGISTRY[("zimage", "2kto4k")] = PID_CHECKPOINT_REGISTRY[("flux", "2kto4k")]
PID_CHECKPOINT_REGISTRY[("zimage_turbo", "2kto4k")] = PID_CHECKPOINT_REGISTRY[("flux", "2kto4k")]


def get_pid_checkpoint(backbone: str, ckpt_type: str = "2k") -> PIDCheckpoint:
    """Return the registered official PID checkpoint for `(backbone, ckpt_type)`.

    `ckpt_type` defaults to `"2k"` so existing call sites keep their pre-2kto4k
    behavior. Raises KeyError with the list of valid keys when the pair is
    unknown — typical cause is asking for a `2kto4k` variant of a backbone
    that doesn't ship one (rae / scale_rae).
    """
    if ckpt_type not in VALID_CKPT_TYPES:
        raise KeyError(f"Unknown ckpt_type {ckpt_type!r}. Valid: {VALID_CKPT_TYPES}")
    try:
        return PID_CHECKPOINT_REGISTRY[(backbone, ckpt_type)]
    except KeyError as exc:
        valid = ", ".join(sorted(f"{b}+{t}" for b, t in PID_CHECKPOINT_REGISTRY))
        raise KeyError(f"Unknown (backbone, ckpt_type)=({backbone!r}, {ckpt_type!r}). Valid: {valid}") from exc


__all__ = [
    "PIDCheckpoint",
    "PID_CHECKPOINT_REGISTRY",
    "VALID_CKPT_TYPES",
    "get_pid_checkpoint",
]

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Check the raised message's 'Valid:' list and pick an existing (backbone, ckpt_type) pair.
2. For rae / scale_rae, use the base '2k' checkpoint — no 2kto4k variant exists.
3. Import PID_CHECKPOINT_REGISTRY and enumerate available pairs programmatically before selecting.

Example fix

// before
get_pid_checkpoint('rae', '2kto4k')  # not shipped
// after
get_pid_checkpoint('rae', '2k')  # or use a backbone that ships 2kto4k

from invokeai.backend.pid._src.inference.checkpoint_registry import PID_CHECKPOINT_REGISTRY
if (backbone, ckpt_type) not in PID_CHECKPOINT_REGISTRY:
    raise KeyError(f'{backbone!r} has no {ckpt_type!r} checkpoint; valid pairs: {sorted(PID_CHECKPOINT_REGISTRY)}')

def has_checkpoint(backbone: str, ckpt_type: str) -> bool:
    from invokeai.backend.pid._src.inference.checkpoint_registry import PID_CHECKPOINT_REGISTRY
    return (backbone, ckpt_type) in PID_CHECKPOINT_REGISTRY

try:
    ckpt = get_pid_checkpoint(backbone, ckpt_type)
except KeyError as e:
    logger.warning('Pair unavailable, falling back: %s', e)
    ckpt = get_pid_checkpoint(backbone, '2k')

When it happens

Trigger: Calling get_pid_checkpoint(backbone, ckpt_type) with a valid ckpt_type but a (backbone, ckpt_type) pair absent from PID_CHECKPOINT_REGISTRY — most commonly ckpt_type='2kto4k' for rae or scale_rae, or a misspelled backbone name.

Common situations: Assuming every backbone has a 2k-to-4k upsample checkpoint; renaming/refactored backbone ids after a version bump; hard-coded backbone strings that no longer match registry keys.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown ckpt_type {ckpt_type!r}. Valid: {VALID_CKPT_TYPES}
• Unknown backbone '{name}'. Available: {list(PIPELINE_REGISTR
• Expected 4-D latent (B, C, H, W) after extraction, got shape
• PiD decoder backbone {backbone!r} is not supported. Expected

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