{"record":{"id":"0df5df4ccbda290c","repo":"invoke-ai/InvokeAI","slug":"unmapped-gemma-2-gguf-tensor-key-key","errorCode":null,"errorMessage":"Unmapped Gemma-2 GGUF tensor key '{key}'","messagePattern":"Unmapped Gemma-2 GGUF tensor key '(.+?)'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/gemma2_encoder.py","lineNumber":70,"sourceCode":"    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,\n    ) -> AnyModel:\n        if not isinstance(config, Gemma2Encoder_Gemma2Encoder_Config):\n            raise ValueError(\"Only Gemma2Encoder_Gemma2Encoder_Config models are supported here.\")\n\n        model_path = Path(config.path)\n\n        match submodel_type:","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/gemma2_encoder.py#L52-L88","documentation":"Raised by _convert_gemma_llamacpp_to_pytorch for any GGUF tensor key that matches neither the blk.N block pattern nor the recognized top-level keys token_embd.weight and output_norm.weight. This catches global/extra tensors (e.g. output.weight, rope_freqs, per-layer norms outside blocks) that the converter has no rule for.","triggerScenarios":"load_gemma2_model_from_gguf on a GGUF containing top-level tensors like output.weight (tied lm_head not expected by the encoder), rope_freqs.weights, or any unexpected root-level key.","commonSituations":"Exporting a full causal-LM GGUF (with lm_head/output tensors) instead of an encoder-only export; GGUFs with extra metadata-like tensors; files converted by third-party scripts adding custom tensor names.","solutions":["Inspect the offending key and add an explicit elif branch to _convert_gemma_llamacpp_to_pytorch mapping or intentionally skipping it","Re-export the GGUF without the extraneous tensor (e.g. drop lm_head for encoder use)","Verify the GGUF is truly Gemma-2 architecture via its metadata before loading"],"exampleFix":"# before\nValueError: Unmapped Gemma-2 GGUF tensor key 'output.weight'\n# after\nelif key == \"output.weight\":\n    continue  # lm_head is not part of the encoder\nelse:\n    raise ValueError(...)","handlingStrategy":"validation","validationCode":"ALLOWED_TOP_LEVEL = {\"token_embd.weight\", \"output_norm.weight\"}\ndef has_unexpected_top_level_keys(keys):\n    import re\n    return [k for k in keys if not re.match(r\"^blk\\.\\d+\\.\", k) and k not in ALLOWED_TOP_LEVEL]","typeGuard":"def is_supported_key(key: str) -> bool:\n    import re\n    return bool(re.match(r\"^blk\\.\\d+\\.[^.]+\", key)) or key in {\"token_embd.weight\", \"output_norm.weight\"}","tryCatchPattern":"try:\n    model = load_gemma2_model_from_gguf(gguf_path, dtype)\nexcept ValueError as e:\n    if \"Unmapped Gemma-2 GGUF tensor key\" in str(e):\n        print(f\"GGUF contains unsupported tensor '{e}'; re-export without it\")\n    else:\n        raise","preventionTips":["Export encoder-only GGUFs (no lm_head/output tensors)","Validate GGUF tensor list against the converter's supported keys before loading","Avoid third-party conversion scripts that inject custom tensor names"],"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"}