{"record":{"id":"bccde06fd4828d97","repo":"invoke-ai/InvokeAI","slug":"missing-keys-loading-model-name-required-parame","errorCode":null,"errorMessage":"Missing keys loading {model_name} (required parameters left on meta): {real_missing}","messagePattern":"Missing keys loading (.+?) \\(required parameters left on meta\\): (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"invokeai/backend/quantization/sdnq/loaders.py","lineNumber":46,"sourceCode":"    For SDNQ folder loads that is dangerous: a partial export, missing shard key or architecture\n    mismatch leaves required parameters on the meta device and returns a model that fails much later\n    during device movement or inference, far from the real cause. This raises with the offending\n    keys instead.\n\n    Args:\n        model_name: Human-readable name for the error message (e.g. \"SDNQ Z-Image transformer\").\n        missing_keys: The ``missing_keys`` returned by ``load_state_dict``.\n        unexpected_keys: The ``unexpected_keys`` returned by ``load_state_dict``.\n        allowed_missing: Keys that are expected to be absent (e.g. tied weights the caller re-shares\n            after load), which must not trigger a failure.\n    \"\"\"\n    allowed = set(allowed_missing)\n    real_missing = [k for k in missing_keys if k not in allowed]\n    unexpected = list(unexpected_keys)\n    if unexpected:\n        raise ValueError(f\"Unexpected keys loading {model_name}: {unexpected}\")\n    if real_missing:\n        raise ValueError(f\"Missing keys loading {model_name} (required parameters left on meta): {real_missing}\")\n\n\ndef _parse_quantization_config(config_path: Path) -> dict[str, Any]:\n    \"\"\"Parse quantization_config.json for SDNQ parameters.\"\"\"\n    if not config_path.exists():\n        return {}\n\n    with open(config_path, \"r\", encoding=\"utf-8\") as f:\n        return json.load(f)\n\n\n_DTYPE_NAME_TO_QUANT_TYPE = {\n    \"uint4\": SDNQQuantizationType.UINT4_ASYM,\n    \"int4\": SDNQQuantizationType.UINT4_ASYM,  # signed naming, same packed storage\n    \"uint5\": SDNQQuantizationType.INT5_ASYM,\n    \"int5\": SDNQQuantizationType.INT5_ASYM,  # SDNQ dynamic-mixed uses this label\n    \"int8\": SDNQQuantizationType.INT8_SYM,\n    \"uint8\": SDNQQuantizationType.UINT8_SYM,","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/quantization/sdnq/loaders.py#L28-L64","documentation":"Companion to the unexpected-keys check: after SDNQ load, keys still reported missing (excluding explicitly allowed_missing) mean required parameters were never materialized and remain on the meta device — the model would fail or silently produce garbage at inference. ValueError lists the unmet keys.","triggerScenarios":"Calling any SDNQ load path (_load_sdnq_transformer, _load_sdnq_vae, _load_sdnq_t5, etc.) where the safetensors files omit tensors the model requires and those keys are not in allowed_missing.","commonSituations":"Truncated or partially downloaded shard files; a checkpoint quantized from an older architecture missing newly added layers; corrupted bundle where some tensors were dropped at quantization time.","solutions":["Re-download the full model files (check shard count/sizes against the repo manifest)","Re-quantize the model so all required parameters are present","If specific keys are legitimately absent (e.g. optional buffers), pass them via allowed_missing"],"exampleFix":"// before\nraise_on_incomplete_sdnq_load(missing_keys, unexpected, model_name)\n// after\nraise_on_incomplete_sdnq_load(missing_keys, unexpected, model_name, allowed_missing=[\"rotary_emb.inv_freq\"])","handlingStrategy":"validation","validationCode":"expected = model.state_dict().keys()\nloaded = set().union(*(load_file(f).keys() for f in shards))\nmissing = set(expected) - loaded\nassert not missing, f\"checkpoint incomplete, missing: {sorted(missing)[:5]}\"","typeGuard":"def checkpoint_is_complete(loaded_keys: set, model_keys) -> bool:\n    return set(model_keys).issubset(loaded_keys)","tryCatchPattern":"try:\n    model = _load_sdnq_vae(path)\nexcept ValueError as e:\n    logger.critical(f\"Model files incomplete — re-download: {e}\")\n    raise","preventionTips":["Verify downloaded file sizes/hashes against the repo manifest after download","Re-download on interrupted transfers instead of resuming into mixed revisions","Keep allowed_missing minimal and explicit"],"tags":["valueerror","missing-keys","meta-device","quantization"],"backgroundTag":"state-dict-missing-keys","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}