What causes "Unknown ckpt_type {ckpt_type!r}. Valid: {VALID_CKPT_TYPES}" in invoke-ai/InvokeAI?

Use a ckpt_type listed in VALID_CKPT_TYPES (default '2k').

invoke-ai/InvokeAI · error · KeyError

Unknown ckpt_type {ckpt_type!r}. Valid: {VALID_CKPT_TYPES}

Error message

Unknown ckpt_type {ckpt_type!r}. Valid: {VALID_CKPT_TYPES}

What it means

get_pid_checkpoint first validates ckpt_type against VALID_CKPT_TYPES. Passing any type outside that set (e.g. a typo or an unsupported resolution variant) raises a KeyError listing the valid types before the registry lookup happens.

Source

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

}
# ZImage and ZImage-Turbo use Flux1's 16-ch VAE for both ckpt types → alias to
# the flux entries. Keep explicit aliases (vs. duplicating) so updating "flux"
# updates these backbones too.
PID_CHECKPOINT_REGISTRY[("zimage_turbo", "2k")] = PID_CHECKPOINT_REGISTRY[("flux", "2k")]
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

Use a ckpt_type listed in VALID_CKPT_TYPES (default '2k').
Fix the casing/typo — the check is case-sensitive exact string comparison.
Import VALID_CKPT_TYPES and validate or surface choices in your CLI/config before calling.

Example fix

// before
get_pid_checkpoint('rae', '2kto4k')  # or typo '2K'
// after
from invokeai.backend.pid._src.inference.checkpoint_registry import VALID_CKPT_TYPES
get_pid_checkpoint('rae', '2k')  # ckpt_type in VALID_CKPT_TYPES

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.pid._src.inference.checkpoint_registry import VALID_CKPT_TYPES
assert ckpt_type in VALID_CKPT_TYPES, f'{ckpt_type!r} not in {VALID_CKPT_TYPES}'

Type guard

def is_valid_ckpt_type(ckpt_type: object) -> bool:
    return isinstance(ckpt_type, str) and ckpt_type in VALID_CKPT_TYPES

Try / catch

try:
    ckpt = get_pid_checkpoint(backbone, ckpt_type)
except KeyError as e:
    logger.error('Bad ckpt_type: %s', e)
    ckpt = get_pid_checkpoint(backbone, '2k')  # safe default

Prevention

Always import VALID_CKPT_TYPES rather than hard-coding type strings.
Validate CLI/config enum values at startup, before any registry call.
Watch string casing — the check is exact and case-sensitive.

When it happens

Trigger: Calling get_pid_checkpoint(backbone, ckpt_type) with ckpt_type not in VALID_CKPT_TYPES — e.g. '4k' when only '2k' and '2kto4k' are valid, or an empty/None value from config.

Common situations: Upgrading code from pre-2kto4k versions where the default was implicit; typos like '2K' vs '2k'; passing a variant the user assumed exists (e.g. 2kto4k for rae/scale_rae backbones that don't ship one — that case instead hits the second KeyError).

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

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