invoke-ai/InvokeAI · error · ValueError

Unmapped Gemma-2 GGUF tensor key component '{component}' (fr

Error message

Unmapped Gemma-2 GGUF tensor key component '{component}' (from '{key}')

What it means

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.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/gemma2_encoder.py:63

def _convert_gemma_llamacpp_to_pytorch(sd: dict[str, Any]) -> dict[str, Any]:
    """Map a llama.cpp Gemma-2 GGUF state dict to Gemma2Model (decoder-only) parameter names.

    Raises ValueError on any tensor key that has no mapping, so a wrong/contaminated checkpoint fails
    loudly here rather than silently dropping weights.
    """
    out: dict[str, Any] = {}
    for key, value in sd.items():
        if not isinstance(key, str):
            out[key] = value
            continue
        m = _GEMMA_BLK_PATTERN.match(key)
        if m:
            idx, rest = m.group(1), m.group(2)
            component, _, suffix = rest.partition(".")
            mapped = _GEMMA_GGUF_KEY_MAP.get(component)
            if mapped is None:
                raise ValueError(f"Unmapped Gemma-2 GGUF tensor key component '{component}' (from '{key}')")
            out[f"layers.{idx}.{mapped}" + (f".{suffix}" if suffix else "")] = value
        elif key == "token_embd.weight":
            out["embed_tokens.weight"] = value
        elif key == "output_norm.weight":
            out["norm.weight"] = value
        else:
            raise ValueError(f"Unmapped Gemma-2 GGUF tensor key '{key}'")
    return out


@ModelLoaderRegistry.register(base=BaseModelType.Any, type=ModelType.Gemma2Encoder, format=ModelFormat.Gemma2Encoder)
class Gemma2EncoderLoader(ModelLoader):
    """Loads a Gemma-2 causal LM directory and exposes its decoder + tokenizer."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Identify the offending component from the message and add a correct mapping to _GEMMA_GGUF_KEY_MAP in gemma2_encoder.py
2. Upgrade/downgrade the GGUF so it was exported by a llama.cpp version compatible with this converter
3. Regenerate the GGUF for a plain dense Gemma-2 model without extra per-layer components
4. If the component should be dropped, handle it explicitly in the converter instead of passing it through

Example fix

# before (gguf has blk.0.attn_kv.weight)
ValueError: Unmapped Gemma-2 GGUF tensor key component 'attn_kv' (from 'blk.0.attn_kv.weight')
# after (add mapping)
_GEMMA_GGUF_KEY_MAP = {..., "attn_k": "self_attn.k_proj", "attn_kv": "self_attn.kv_proj"}

import re
_BLK = re.compile(r"^blk\.(\d+)\.([^.]+)(?:\.(.+))?$")
_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"}
def gguf_components_supported(keys):
    bad = [k for k in keys if (m := _BLK.match(k)) and m.group(2) not in _KNOWN_COMPONENTS]
    return not bad, bad

def is_mapped_component(component: str) -> bool:
    return component in _GEMMA_GGUF_KEY_MAP

try:
    model = load_gemma2_model_from_gguf(gguf_path, dtype)
except ValueError as e:
    if "Unmapped Gemma-2 GGUF tensor key component" in str(e):
        print(f"GGUF uses unsupported tensor keys: {e}; re-export or update the key map")
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Unmapped Gemma-2 GGUF tensor key '{key}'
• Gemma2 GGUF embedding_length {hidden_size} is incompatible w
• Only Gemma2Encoder_GGUF_Config models are supported here.
• Unexpected keys loading Gemma-2 GGUF encoder: {unexpected[:1
• Gemma-2 GGUF encoder has parameters left on the meta device

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