{"record":{"id":"ca020931eea09b2e","repo":"invoke-ai/InvokeAI","slug":"gguf-file-is-missing-the-general-architecture-me","errorCode":null,"errorMessage":"GGUF file is missing the 'general.architecture' metadata field","messagePattern":"GGUF file is missing the 'general\\.architecture' metadata field","errorType":"validation","errorClass":"NotAMatchError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/configs/gemma2_encoder.py","lineNumber":104,"sourceCode":"\n        return cls(**override_fields)\n\n\ndef _read_gguf_arch_and_hidden_size(path: Path) -> tuple[str, int | None]:\n    \"\"\"Read (general.architecture, <arch>.embedding_length) from a GGUF file's metadata.\n\n    Raises NotAMatchError if the file is not a readable GGUF or is missing the architecture marker.\n    \"\"\"\n    import gguf\n\n    try:\n        reader = gguf.GGUFReader(path)\n    except Exception as e:\n        raise NotAMatchError(f\"not a readable GGUF file: {e}\") from e\n\n    arch_field = reader.fields.get(\"general.architecture\")\n    if arch_field is None:\n        raise NotAMatchError(\"GGUF file is missing the 'general.architecture' metadata field\")\n    architecture = str(arch_field.contents())\n\n    hidden_field = reader.fields.get(f\"{architecture}.embedding_length\")\n    hidden_size = int(hidden_field.contents()) if hidden_field is not None else None\n    return architecture, hidden_size\n\n\nclass Gemma2Encoder_GGUF_Config(Config_Base):\n    \"\"\"Single-file GGUF-quantized Gemma-2-2b encoder for PiD (llama.cpp GGUF, e.g. gemma-2-2b-it-Q4_K_M.gguf).\n\n    Unlike the diffusers-directory config, this is a single ``.gguf`` file: the model config and the\n    tokenizer are read from the GGUF metadata, so no companion config.json / tokenizer files are required.\n    The weights are loaded natively by ``Gemma2EncoderGGUFLoader`` — the large 2D projections stay\n    quantized as ``GGMLTensor`` and are dequantized on demand by the model cache, rather than being fully\n    dequantized into memory at load time. Only Gemma-2-2b (2304-dim) is accepted, matching PiD's fixed\n    caption projection; 9B/27B GGUFs are rejected here as for the directory config.\n    \"\"\"\n","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/configs/gemma2_encoder.py#L86-L122","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before (inspect)\ngguf-dump model.gguf | grep general.architecture  # -> missing\n// after\npython convert_hf_to_gguf.py <hf-model-dir> --outfile model.gguf  # writes general.architecture='gemma2'","handlingStrategy":"validation","validationCode":"def gguf_has_arch(path) -> bool:\n    import gguf\n    try:\n        reader = gguf.GGUFReader(path)\n    except Exception:\n        return False\n    return \"general.architecture\" in reader.fields","typeGuard":"def is_standard_llamacpp_gguf(p: Path) -> bool:\n    import gguf\n    try:\n        return \"general.architecture\" in gguf.GGUFReader(p).fields\n    except Exception:\n        return False","tryCatchPattern":"try:\n    import_model(gguf_path)\nexcept NotAMatchError as e:\n    if \"missing the 'general.architecture'\" in str(e):\n        print(\"Non-standard GGUF — re-convert with llama.cpp convert_hf_to_gguf.py or use an official quant\")","preventionTips":["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"],"tags":["gguf","metadata","model-import"],"backgroundTag":"missing-gguf-metadata","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}