{"record":{"id":"36234957e232292b","repo":"invoke-ai/InvokeAI","slug":"unknown-backbone-ckpt-type-backbone-r-ckpt","errorCode":null,"errorMessage":"Unknown (backbone, ckpt_type)=({backbone!r}, {ckpt_type!r}). Valid: {valid}","messagePattern":"Unknown \\(backbone, ckpt_type\\)=\\((.+?), (.+?)\\)\\. Valid: (.+?)","errorType":"exception","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/pid/_src/inference/checkpoint_registry.py","lineNumber":114,"sourceCode":"PID_CHECKPOINT_REGISTRY[(\"zimage\", \"2kto4k\")] = PID_CHECKPOINT_REGISTRY[(\"flux\", \"2kto4k\")]\nPID_CHECKPOINT_REGISTRY[(\"zimage_turbo\", \"2kto4k\")] = PID_CHECKPOINT_REGISTRY[(\"flux\", \"2kto4k\")]\n\n\ndef get_pid_checkpoint(backbone: str, ckpt_type: str = \"2k\") -> PIDCheckpoint:\n    \"\"\"Return the registered official PID checkpoint for `(backbone, ckpt_type)`.\n\n    `ckpt_type` defaults to `\"2k\"` so existing call sites keep their pre-2kto4k\n    behavior. Raises KeyError with the list of valid keys when the pair is\n    unknown — typical cause is asking for a `2kto4k` variant of a backbone\n    that doesn't ship one (rae / scale_rae).\n    \"\"\"\n    if ckpt_type not in VALID_CKPT_TYPES:\n        raise KeyError(f\"Unknown ckpt_type {ckpt_type!r}. Valid: {VALID_CKPT_TYPES}\")\n    try:\n        return PID_CHECKPOINT_REGISTRY[(backbone, ckpt_type)]\n    except KeyError as exc:\n        valid = \", \".join(sorted(f\"{b}+{t}\" for b, t in PID_CHECKPOINT_REGISTRY))\n        raise KeyError(f\"Unknown (backbone, ckpt_type)=({backbone!r}, {ckpt_type!r}). Valid: {valid}\") from exc\n\n\n__all__ = [\n    \"PIDCheckpoint\",\n    \"PID_CHECKPOINT_REGISTRY\",\n    \"VALID_CKPT_TYPES\",\n    \"get_pid_checkpoint\",\n]\n","sourceCodeStart":96,"sourceCodeEnd":123,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/pid/_src/inference/checkpoint_registry.py#L96-L123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the raised message's 'Valid:' list and pick an existing (backbone, ckpt_type) pair.","For rae / scale_rae, use the base '2k' checkpoint — no 2kto4k variant exists.","Import PID_CHECKPOINT_REGISTRY and enumerate available pairs programmatically before selecting."],"exampleFix":"// before\nget_pid_checkpoint('rae', '2kto4k')  # not shipped\n// after\nget_pid_checkpoint('rae', '2k')  # or use a backbone that ships 2kto4k","handlingStrategy":"validation","validationCode":"from invokeai.backend.pid._src.inference.checkpoint_registry import PID_CHECKPOINT_REGISTRY\nif (backbone, ckpt_type) not in PID_CHECKPOINT_REGISTRY:\n    raise KeyError(f'{backbone!r} has no {ckpt_type!r} checkpoint; valid pairs: {sorted(PID_CHECKPOINT_REGISTRY)}')","typeGuard":"def has_checkpoint(backbone: str, ckpt_type: str) -> bool:\n    from invokeai.backend.pid._src.inference.checkpoint_registry import PID_CHECKPOINT_REGISTRY\n    return (backbone, ckpt_type) in PID_CHECKPOINT_REGISTRY","tryCatchPattern":"try:\n    ckpt = get_pid_checkpoint(backbone, ckpt_type)\nexcept KeyError as e:\n    logger.warning('Pair unavailable, falling back: %s', e)\n    ckpt = get_pid_checkpoint(backbone, '2k')","preventionTips":["Enumerate PID_CHECKPOINT_REGISTRY keys when building UIs/configs instead of hard-coding options.","Remember rae and scale_rae have no 2kto4k variant.","Verify backbone names after every library version upgrade."],"tags":["keyerror","checkpoint-registry","pid","backbone"],"backgroundTag":"invalid-enum-value","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}