invoke-ai/InvokeAI · warning · NotAMatchError

not a .gguf file: {mod.path.name}

Error message

not a .gguf file: {mod.path.name}

What it means

NotAMatchError raised by Gemma2Encoder_GGUF_Config.from_model_on_disk when the candidate path is not a file ending in .gguf (case-insensitive). This GGUF config only handles single-file GGUF models; any other file name simply doesn't match, and the model factory tries other config classes.

Source

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

    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.
    """

    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

1. Rename the file so it ends in .gguf if it actually is a GGUF (check magic bytes first)
2. If it is safetensors/bin, let the directory-based Gemma2Encoder config or the appropriate safetensors config classify it instead
3. Do not force ModelFormat.GGUFQuantized on non-GGUF files when importing

Example fix

// before
mv gemma-2-2b-it-Q4_K_M gemma-2-2b-it-Q4_K_M.gguf.check  # wrong: no .gguf suffix
// after
mv gemma-2-2b-it-Q4_K_M gemma-2-2b-it-Q4_K_M.gguf

from pathlib import Path

def is_gguf_path(p: str | Path) -> bool:
    return Path(p).is_file() and Path(p).suffix.lower() == ".gguf"

def is_gguf_file(p: Path) -> bool:
    return p.suffix.lower() == ".gguf"

if not is_gguf_path(path):
    print("Gemma2Encoder_GGUF_Config only accepts .gguf files; use the directory config for safetensors")
else:
    try:
        import_model(path)
    except NotAMatchError as e:
        handle(e)

When it happens

Trigger: Model scan or from_model_on_disk dispatching a non-.gguf file (e.g. .safetensors, .bin, .ckpt, .zip) to Gemma2Encoder_GGUF_Config, typically when the user forces the format or the file lives in a folder being scanned as GGUF.

Common situations: Pointing InvokeAI at a single safetensors file expecting GGUF support; a GGUF renamed without the extension; scanning a mixed folder where non-GGUF files get probed against this config.

Related errors

• not a readable GGUF file: {e}
• GGUF file is missing the 'general.architecture' metadata fie
• GGUF architecture '{architecture}' is not 'gemma2'
• File extension {path.suffix} is not a recognized model forma
• Gemma2 hidden_size {hidden_size} is incompatible with PiD, w

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