invoke-ai/InvokeAI · error · NotAMatchError

not a readable GGUF file: {e}

Error message

not a readable GGUF file: {e}

What it means

NotAMatchError raised by _read_gguf_arch_and_hidden_size when gguf.GGUFReader(path) throws while opening the file, meaning the .gguf file cannot be parsed. The original reader exception text is embedded in the message. This is part of GGUF Gemma2 encoder identification, so any unreadable file is treated as 'not a match' and classification moves on to other config classes.

Source

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

        # Sanity check that tokenizer files live alongside the model (PiD calls
        # AutoTokenizer.from_pretrained on the same directory).
        if not any((mod.path / f).exists() for f in ("tokenizer.json", "tokenizer.model")):
            raise NotAMatchError("directory does not contain Gemma2 tokenizer files (tokenizer.json/tokenizer.model)")

        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

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Re-download the .gguf file and verify its size/checksum against the HuggingFace repo
2. If the repo uses git-lfs, run 'git lfs pull' so the real binary replaces the pointer file
3. Confirm the file starts with the GGUF magic bytes (e.g. head -c 4 file.gguf shows 'GGUF')
4. Check the embedded exception text in the message for the underlying cause (permission denied vs parse error)

Example fix

// before
wget -c https://huggingface.co/.../gemma-2-2b-it-Q4_K_M.gguf  # interrupted, truncated
// after
huggingface-cli download <repo> gemma-2-2b-it-Q4_K_M.gguf  # verifies size/hash

from pathlib import Path

def looks_like_gguf(path: str | Path) -> bool:
    p = Path(path)
    if p.suffix.lower() != ".gguf" or not p.is_file():
        return False
    try:
        with open(p, "rb") as f:
            return f.read(4) == b"GGUF"
    except OSError:
        return False

def is_plausible_gguf_download(p: Path, expected_min_bytes: int) -> bool:
    return looks_like_gguf(p) and p.stat().st_size >= expected_min_bytes

try:
    import_model(gguf_path)
except NotAMatchError as e:
    if "not a readable GGUF" in str(e):
        print("File is truncated/corrupt — re-download and verify size or sha256")

When it happens

Trigger: from_model_on_disk on a file with a .gguf suffix whose contents are not valid GGUF: truncated/partial download, HTML error page saved as .gguf, corrupted or LFS-pointer file, or a file with a .gguf extension that is actually a different format.

Common situations: Interrupted downloads from HuggingFace (partial size); git-lfs pointer files checked out without 'git lfs pull'; CDN error pages saved instead of the model; renamed non-GGUF binaries.

Related errors

• GGUF file is missing the 'general.architecture' metadata fie
• not a .gguf file: {mod.path.name}
• GGUF architecture '{architecture}' is not 'gemma2'
• Cannot split QKV tensor '{key}': first dimension ({tensor.sh
• Expected 2D embed_tokens weight tensor, got shape {embed_sha

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