invoke-ai/InvokeAI · error · NotAMatchError

GGUF file is missing the 'general.architecture' metadata fie

Error message

GGUF file is missing the 'general.architecture' metadata field

What it means

NotAMatchError raised by _read_gguf_arch_and_hidden_size when the GGUF file parses but has no 'general.architecture' metadata field. That field is required both to identify the GGUF as gemma2 and to locate the '<arch>.embedding_length' key used for the 2304-dim compatibility check.

Source

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

        return cls(**override_fields)


def _read_gguf_arch_and_hidden_size(path: Path) -> tuple[str, int | None]:
    """Read (general.architecture, <arch>.embedding_length) from a GGUF file's metadata.

    Raises NotAMatchError if the file is not a readable GGUF or is missing the architecture marker.
    """
    import gguf

    try:
        reader = gguf.GGUFReader(path)
    except Exception as e:
        raise NotAMatchError(f"not a readable GGUF file: {e}") from e

    arch_field = reader.fields.get("general.architecture")
    if arch_field is None:
        raise NotAMatchError("GGUF file is missing the 'general.architecture' metadata field")
    architecture = str(arch_field.contents())

    hidden_field = reader.fields.get(f"{architecture}.embedding_length")
    hidden_size = int(hidden_field.contents()) if hidden_field is not None else None
    return architecture, hidden_size


class Gemma2Encoder_GGUF_Config(Config_Base):
    """Single-file GGUF-quantized Gemma-2-2b encoder for PiD (llama.cpp GGUF, e.g. gemma-2-2b-it-Q4_K_M.gguf).

    Unlike the diffusers-directory config, this is a single ``.gguf`` file: the model config and the
    tokenizer are read from the GGUF metadata, so no companion config.json / tokenizer files are required.
    The weights are loaded natively by ``Gemma2EncoderGGUFLoader`` — the large 2D projections stay
    quantized as ``GGMLTensor`` and are dequantized on demand by the model cache, rather than being fully
    dequantized into memory at load time. Only Gemma-2-2b (2304-dim) is accepted, matching PiD's fixed
    caption projection; 9B/27B GGUFs are rejected here as for the directory config.
    """

View on GitHub (pinned to 0b6a024f2f)

Solutions

Re-convert or re-download a GGUF produced by a standard llama.cpp convert script, which always writes general.architecture
Verify metadata with 'gguf-dump file.gguf' (or the gguf Python package) and confirm general.architecture is present
Use an official gemma-2-2b-it GGUF build instead of a custom re-pack

Example fix

// before (inspect)
gguf-dump model.gguf | grep general.architecture  # -> missing
// after
python convert_hf_to_gguf.py <hf-model-dir> --outfile model.gguf  # writes general.architecture='gemma2'

Defensive patterns

Strategy: validation

Validate before calling

def gguf_has_arch(path) -> bool:
    import gguf
    try:
        reader = gguf.GGUFReader(path)
    except Exception:
        return False
    return "general.architecture" in reader.fields

Type guard

def is_standard_llamacpp_gguf(p: Path) -> bool:
    import gguf
    try:
        return "general.architecture" in gguf.GGUFReader(p).fields
    except Exception:
        return False

Try / catch

try:
    import_model(gguf_path)
except NotAMatchError as e:
    if "missing the 'general.architecture'" in str(e):
        print("Non-standard GGUF — re-convert with llama.cpp convert_hf_to_gguf.py or use an official quant")

Prevention

Only use GGUFs produced by standard llama.cpp conversion scripts or trusted quant collections
Run gguf-dump file.gguf to inspect metadata before importing
Avoid repacked/custom GGUFs that strip general.* metadata

When it happens

Trigger: from_model_on_disk on a .gguf file whose metadata lacks general.architecture — typically non-llama.cpp GGUFs, hand-crafted GGUFs written without general metadata, or files from tools that strip/omit metadata keys.

Common situations: GGUFs produced by old or exotic converters, custom quantizations re-packed without metadata, or 'GGUF-like' files from tools that don't follow the llama.cpp spec.

Related errors

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