invoke-ai/InvokeAI · error · NotAMatchError

expected a .safetensors file, got {mod.path.suffix or '(no s

Error message

expected a .safetensors file, got {mod.path.suffix or '(no suffix)'}

What it means

Raised as a NotAMatchError by Qwen3VLEncoder_Checkpoint_Config.from_model_on_disk when model identification is asked to classify a single-file model whose extension is not .safetensors. This config class only supports single-file Qwen3-VL encoder checkpoints in safetensors format; anything else (a .bin, .gguf, or a file with no extension) cannot be matched and the identifier moves on.

Source

Thrown at invokeai/backend/model_manager/configs/qwen3_vl_encoder.py:188

    Distinguished from the text-only ``Qwen3Encoder`` checkpoint (Z-Image) by the presence of the
    Qwen3-VL visual tower. The tokenizer is not bundled in single-file checkpoints and is pulled from
    HuggingFace (``Qwen/Qwen3-VL-4B-Instruct``) by the loader.
    """

    base: Literal[BaseModelType.Any] = Field(default=BaseModelType.Any)
    type: Literal[ModelType.Qwen3VLEncoder] = Field(default=ModelType.Qwen3VLEncoder)
    format: Literal[ModelFormat.Checkpoint] = Field(default=ModelFormat.Checkpoint)
    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() != ".safetensors":
            raise NotAMatchError(f"expected a .safetensors file, got {mod.path.suffix or '(no suffix)'}")

        state_dict = mod.load_state_dict()
        if not _is_qwen3_vl_encoder_state_dict(state_dict):
            raise NotAMatchError("state dict does not look like a single-file Qwen3-VL encoder")
        _validate_krea2_qwen3_vl_checkpoint_shape(state_dict)

        return cls(**override_fields)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Convert the checkpoint to safetensors (e.g. convert via safetensors.torch.save_file or a conversion script) and re-import.
2. Download the .safetensors variant of the encoder (ComfyUI qwen3vl_4b_* safetensors releases) instead of the .bin/.gguf one.
3. Restore the .safetensors extension if the file was renamed; verify with `ls`/`file` that it is actually a safetensors file.
4. Use the appropriate config class for the actual format (e.g. GGUF or diffusers-folder matchers) rather than this checkpoint matcher.

Example fix

// before
qwen_2.5_vl_7b.bin   -> import -> NotAMatchError

// after
python -c "from safetensors.torch import load_file, save_file; import torch; sd=torch.load('qwen_2.5_vl_7b.bin',map_location='cpu'); save_file(sd,'qwen_2.5_vl_7b.safetensors')"
qwen_2.5_vl_7b.safetensors -> import -> matched

from pathlib import Path

def ensure_safetensors_file(path: Path) -> None:
    if not path.is_file():
        raise ValueError(f"{path} is not a file")
    if path.suffix.lower() != ".safetensors":
        raise ValueError(f"expected .safetensors, got {path.suffix or '(no suffix)'}")

from pathlib import Path

def is_safetensors_file(p: Path) -> bool:
    return p.is_file() and p.suffix.lower() == ".safetensors"

try:
    invokeai_model_manager.probe(file_path)
except NotAMatchError as e:
    if str(e).startswith("expected a .safetensors file"):
        converted = convert_to_safetensors(file_path)  # e.g. .bin -> .safetensors
        invokeai_model_manager.probe(converted)
    else:
        raise

When it happens

Trigger: Running model import/probe on a single file whose mod.path.suffix.lower() != '.safetensors' — e.g. a .pth/.bin PyTorch checkpoint, .gguf quantized file, .ckpt, or an extension-less file — with the Qwen3-VL checkpoint config in the matching candidate list.

Common situations: Downloading a ComfyUI-style encoder in .gguf or fp16 .bin form; renaming a file and losing the extension; older PyTorch checkpoints saved as pytorch_model.bin; confusing a directory-format model with the single-file format.

Related errors

• standalone Qwen3-VL encoder directory does not contain token
• state dict does not look like a single-file Qwen3-VL encoder
• directory looks like a full diffusers pipeline (has model_in
• missing text_encoder/ subfolder
• unrecognized token vector length {token_vector_length}

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