{"record":{"id":"5573d744947636e8","repo":"invoke-ai/InvokeAI","slug":"unmapped-gemma-2-gguf-tensor-key-component-compo","errorCode":null,"errorMessage":"Unmapped Gemma-2 GGUF tensor key component '{component}' (from '{key}')","messagePattern":"Unmapped Gemma-2 GGUF tensor key component '(.+?)' \\(from '(.+?)'\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/gemma2_encoder.py","lineNumber":63,"sourceCode":"\ndef _convert_gemma_llamacpp_to_pytorch(sd: dict[str, Any]) -> dict[str, Any]:\n    \"\"\"Map a llama.cpp Gemma-2 GGUF state dict to Gemma2Model (decoder-only) parameter names.\n\n    Raises ValueError on any tensor key that has no mapping, so a wrong/contaminated checkpoint fails\n    loudly here rather than silently dropping weights.\n    \"\"\"\n    out: dict[str, Any] = {}\n    for key, value in sd.items():\n        if not isinstance(key, str):\n            out[key] = value\n            continue\n        m = _GEMMA_BLK_PATTERN.match(key)\n        if m:\n            idx, rest = m.group(1), m.group(2)\n            component, _, suffix = rest.partition(\".\")\n            mapped = _GEMMA_GGUF_KEY_MAP.get(component)\n            if mapped is None:\n                raise ValueError(f\"Unmapped Gemma-2 GGUF tensor key component '{component}' (from '{key}')\")\n            out[f\"layers.{idx}.{mapped}\" + (f\".{suffix}\" if suffix else \"\")] = value\n        elif key == \"token_embd.weight\":\n            out[\"embed_tokens.weight\"] = value\n        elif key == \"output_norm.weight\":\n            out[\"norm.weight\"] = value\n        else:\n            raise ValueError(f\"Unmapped Gemma-2 GGUF tensor key '{key}'\")\n    return out\n\n\n@ModelLoaderRegistry.register(base=BaseModelType.Any, type=ModelType.Gemma2Encoder, format=ModelFormat.Gemma2Encoder)\nclass Gemma2EncoderLoader(ModelLoader):\n    \"\"\"Loads a Gemma-2 causal LM directory and exposes its decoder + tokenizer.\"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/gemma2_encoder.py#L45-L81","documentation":"Raised by _convert_gemma_llamacpp_to_pytorch when a llama.cpp GGUF tensor key of the form blk.N.<component>.* has a component that is not present in the static _GEMMA_GGUF_KEY_MAP. The converter only knows how to rename components it has explicitly mapped (attn, ffn, etc.), so an unknown component would silently produce a mis-mapped weight, and the library fails fast instead.","triggerScenarios":"Calling load_gemma2_model_from_gguf on a GGUF whose block tensors contain a component name outside _GEMMA_GGUF_KEY_MAP — e.g. a newer llama.cpp export adding a renamed or extra module (blk.12.attn_kv.weight, blk.0.expert.0.weight), or a non-Gemma architecture mislabeled as Gemma-2.","commonSituations":"Using a GGUF produced by a newer llama.cpp version than the map in this file supports; loading a MoE or quantization-variant GGUF with extra per-layer tensors; hand-editing or re-keying GGUF tensors; testing the converter with a deliberately unmapped key (as test_convert_rejects_unmapped_keys does).","solutions":["Identify the offending component from the message and add a correct mapping to _GEMMA_GGUF_KEY_MAP in gemma2_encoder.py","Upgrade/downgrade the GGUF so it was exported by a llama.cpp version compatible with this converter","Regenerate the GGUF for a plain dense Gemma-2 model without extra per-layer components","If the component should be dropped, handle it explicitly in the converter instead of passing it through"],"exampleFix":"# before (gguf has blk.0.attn_kv.weight)\nValueError: Unmapped Gemma-2 GGUF tensor key component 'attn_kv' (from 'blk.0.attn_kv.weight')\n# after (add mapping)\n_GEMMA_GGUF_KEY_MAP = {..., \"attn_k\": \"self_attn.k_proj\", \"attn_kv\": \"self_attn.kv_proj\"}","handlingStrategy":"validation","validationCode":"import re\n_BLK = re.compile(r\"^blk\\.(\\d+)\\.([^.]+)(?:\\.(.+))?$\")\n_KNOWN_COMPONENTS = {\"attn_q\", \"attn_k\", \"attn_v\", \"attn_output\", \"ffn_gate\", \"ffn_up\", \"ffn_down\", \"attn_norm\", \"ffn_norm\", \"post_attention_norm\", \"post_ffw_norm\"}\ndef gguf_components_supported(keys):\n    bad = [k for k in keys if (m := _BLK.match(k)) and m.group(2) not in _KNOWN_COMPONENTS]\n    return not bad, bad","typeGuard":"def is_mapped_component(component: str) -> bool:\n    return component in _GEMMA_GGUF_KEY_MAP","tryCatchPattern":"try:\n    model = load_gemma2_model_from_gguf(gguf_path, dtype)\nexcept ValueError as e:\n    if \"Unmapped Gemma-2 GGUF tensor key component\" in str(e):\n        print(f\"GGUF uses unsupported tensor keys: {e}; re-export or update the key map\")\n    else:\n        raise","preventionTips":["Pin the llama.cpp version used to export GGUFs to one compatible with the converter map","Inspect GGUF tensor names (gguf CLI) before loading a new export","Keep _GEMMA_GGUF_KEY_MAP updated when adopting new Gemma GGUF exports"],"tags":["gguf","model-conversion","gemma2","key-mapping"],"backgroundTag":"unmapped-tensor-key","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}