invoke-ai/InvokeAI · error · NotAMatchError

text_encoder class is {sorted(candidates) or 'unknown'}, exp

Error message

text_encoder class is {sorted(candidates) or 'unknown'}, expected one of {sorted(_RECOGNIZED_TEXT_ENCODER_CLASSES)}

What it means

`NotAMatchError` raised when `text_encoder/config.json` parses but its `_class_name` / `architectures` do not intersect `_RECOGNIZED_TEXT_ENCODER_CLASSES` — i.e. the folder holds a text encoder InvokeAI does not classify as a Qwen2.5-VL/Qwen2-VL encoder (e.g. T5, CLIP, or an unknown class). The message lists the found candidates and the accepted set.

Source

Thrown at invokeai/backend/model_manager/configs/qwen_vl_encoder.py:109

        if not tokenizer_dir.is_dir():
            raise NotAMatchError("missing tokenizer/ subfolder")

        config_path = text_encoder_dir / "config.json"
        if not config_path.is_file():
            raise NotAMatchError(f"missing {config_path}")

        try:
            with open(config_path, "r", encoding="utf-8") as f:
                cfg = json.load(f)
        except (OSError, json.JSONDecodeError) as e:
            raise NotAMatchError(f"could not read text_encoder/config.json: {e}") from e

        class_name = cfg.get("_class_name")
        architectures = cfg.get("architectures") or []
        candidates = {class_name, *architectures} - {None}

        if not candidates & _RECOGNIZED_TEXT_ENCODER_CLASSES:
            raise NotAMatchError(
                f"text_encoder class is {sorted(candidates) or 'unknown'}, "
                f"expected one of {sorted(_RECOGNIZED_TEXT_ENCODER_CLASSES)}"
            )

        return cls(**override_fields)


class QwenVLEncoder_Checkpoint_Config(Checkpoint_Config_Base, Config_Base):
    """Configuration for single-file Qwen2.5-VL encoder checkpoints (safetensors).

    This matches ComfyUI-style consolidated single-file encoders such as
    `qwen_2.5_vl_7b_fp8_scaled.safetensors`, which bundle the language model
    and the visual tower into one file (typically with FP8 + per-tensor
    `weight_scale` ComfyUI quantization).

    The matching tokenizer + processor are pulled from HuggingFace
    (`Qwen/Qwen2.5-VL-7B-Instruct`) on first use and cached for offline use.
    """

View on GitHub (pinned to 0b6a024f2f)

Solutions

Open `text_encoder/config.json` and check `_class_name` / `architectures`; they must be a recognized Qwen2-VL/Qwen2.5-VL text encoder class
Replace `text_encoder/` with the folder from an official Qwen2.5-VL/Qwen2-VL release
If classes were renamed by a library update, refresh config.json from the upstream repo rather than hand-editing
Confirm you are installing the right model type — non-Qwen encoders will never match this config

Example fix

// before: text_encoder/config.json
{"_class_name": "CLIPTextModel", ...}
// after
{"_class_name": "Qwen2VLForConditionalGeneration", "architectures": ["Qwen2VLForConditionalGeneration"], ...}

Defensive patterns

Strategy: validation

Validate before calling

import json
from pathlib import Path

EXPECTED = {"Qwen2VLForConditionalGeneration", "Qwen2_5_VLForConditionalGeneration"}  # check _RECOGNIZED_TEXT_ENCODER_CLASSES

def is_recognized_encoder(model_dir: Path) -> bool:
    cfg = json.loads((model_dir / "text_encoder" / "config.json").read_text())
    cands = {cfg.get("_class_name"), *(cfg.get("architectures") or [])} - {None}
    return bool(cands & EXPECTED)

Try / catch

try:
    cfg = QwenVLTextEncoderConfig.from_model_on_disk(mod, override_fields)
except NotAMatchError as e:
    print(e)  # lists found classes vs expected; swap in correct text_encoder/ folder
    raise

Prevention

Keep component folders from the same parent checkpoint together — never mix text encoders across models
Check `_class_name` in config.json before installing custom merges
If a library update renamed classes, refresh config.json from upstream

When it happens

Trigger: Pointing the installer at a multi-model dump where `text_encoder/` belongs to a different architecture; a HF repo changed `_class_name` across versions; a custom or renamed encoder class in config.json.

Common situations: Mixing components from different checkpoints (e.g. SDXL's text_encoder dropped into a Qwen VL folder), renamed classes in newer transformers versions, fine-tune repos that override `architectures`, or manually edited config.json.

Related errors

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