invoke-ai/InvokeAI · error · NotAMatchError

Gemma2 GGUF embedding_length {hidden_size} is incompatible w

Error message

Gemma2 GGUF embedding_length {hidden_size} is incompatible with PiD, which requires {_PID_GEMMA_HIDDEN_SIZE} (Gemma-2-2b); 9B/27B variants are not supported.

What it means

NotAMatchError raised by Gemma2Encoder_GGUF_Config.from_model_on_disk when a gemma2-architecture GGUF reports an embedding_length other than 2304. PiD's caption projection is fixed to Gemma-2-2b's 2304-dim hidden state, so 9B (3584) and 27B (4608) GGUFs are rejected at import time instead of failing later with a matrix-shape error during inference.

Source

Thrown at invokeai/backend/model_manager/configs/gemma2_encoder.py:140

    base: Literal[BaseModelType.Any] = Field(default=BaseModelType.Any)
    type: Literal[ModelType.Gemma2Encoder] = Field(default=ModelType.Gemma2Encoder)
    format: Literal[ModelFormat.GGUFQuantized] = Field(default=ModelFormat.GGUFQuantized)
    cpu_only: bool | None = Field(default=None, description="Whether this model should run on CPU only")

    @classmethod
    def from_model_on_disk(cls, mod: ModelOnDisk, override_fields: dict[str, Any]) -> Self:
        raise_if_not_file(mod)
        raise_for_override_fields(cls, override_fields)

        if mod.path.suffix.lower() != ".gguf":
            raise NotAMatchError(f"not a .gguf file: {mod.path.name}")

        architecture, hidden_size = _read_gguf_arch_and_hidden_size(mod.path)
        if architecture != "gemma2":
            raise NotAMatchError(f"GGUF architecture '{architecture}' is not 'gemma2'")
        if hidden_size != _PID_GEMMA_HIDDEN_SIZE:
            raise NotAMatchError(
                f"Gemma2 GGUF embedding_length {hidden_size} is incompatible with PiD, which requires "
                f"{_PID_GEMMA_HIDDEN_SIZE} (Gemma-2-2b); 9B/27B variants are not supported."
            )

        return cls(**override_fields)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Use a Gemma-2-2b GGUF (embedding_length 2304), e.g. gemma-2-2b-it-Q4_K_M.gguf
Check before importing: gguf-dump file.gguf | grep embedding_length
Verify the GGUF was built from gemma-2-2b-it, not the 9b/27b checkpoints

Example fix

// before (inspect)
<gemma2>.embedding_length = 3584  # gemma-2-9b-it GGUF
// after
<gemma2>.embedding_length = 2304  # gemma-2-2b-it GGUF

Defensive patterns

Strategy: validation

Validate before calling

def gguf_embedding_length(path) -> int | None:
    import gguf
    try:
        reader = gguf.GGUFReader(path)
        field = reader.fields.get("general.architecture")
        if field is None:
            return None
        arch = str(field.contents())
        hidden = reader.fields.get(f"{arch}.embedding_length")
        return int(hidden.contents()) if hidden else None
    except Exception:
        return None

assert gguf_embedding_length("model.gguf") == 2304

Type guard

def is_gemma_2_2b_gguf(p: Path) -> bool:
    return gguf_architecture(p) == "gemma2" and gguf_embedding_length(p) == 2304

Try / catch

try:
    import_model(gguf_path)
except NotAMatchError as e:
    if "embedding_length" in str(e):
        print("9B/27B GGUF not supported by PiD — use gemma-2-2b-it (2304-dim)")

Prevention

Confirm embedding_length == 2304 via gguf-dump before adding any gemma2 GGUF as a PiD encoder
In quantization collections, pick files explicitly named gemma-2-2b-it-*
Don't assume quantization level changes compatibility — it's the base model size that matters

When it happens

Trigger: from_model_on_disk on a .gguf with general.architecture=='gemma2' whose <arch>.embedding_length != 2304 — i.e. gemma-2-9b-it or gemma-2-27b-it quantizations.

Common situations: User picks the largest GGUF in a bartowski-style collection assuming bigger is better; converts gemma-2-9b/27b to GGUF themselves and tries to use it as the PiD encoder.

Related errors

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