{"record":{"id":"8501a629d87b9bdb","repo":"invoke-ai/InvokeAI","slug":"hidden-size-does-not-match-a-known-qwen3-variant","errorCode":null,"errorMessage":"hidden size does not match a known Qwen3 variant","messagePattern":"hidden size does not match a known Qwen3 variant","errorType":"exception","errorClass":"NotAMatchError","httpStatus":null,"severity":"warning","filePath":"invokeai/backend/model_manager/configs/qwen3_encoder.py","lineNumber":226,"sourceCode":"\n        cls._validate_does_not_look_like_gguf_quantized(mod)\n\n        # Determine variant from state dict\n        variant = cls._get_variant_or_default(mod)\n\n        return cls(variant=variant, **override_fields)\n\n    @classmethod\n    def _get_variant_or_default(cls, mod: ModelOnDisk) -> Qwen3VariantType:\n        \"\"\"Get the variant from state dict, raising NotAMatch when the size does not match a known Qwen3 variant.\n\n        We previously defaulted to 4B for unknown sizes, but that swallowed other causal-LM GGUFs\n        (Mistral, Llama, ...) which share llama.cpp tensor naming with Qwen3.\n        \"\"\"\n        state_dict = mod.load_state_dict()\n        variant = _get_qwen3_variant_from_state_dict(state_dict)\n        if variant is None:\n            raise NotAMatchError(\"hidden size does not match a known Qwen3 variant\")\n        return variant\n\n    @classmethod\n    def _validate_looks_like_qwen3_model(cls, mod: ModelOnDisk) -> None:\n        state_dict = mod.load_state_dict()\n        if not _has_qwen3_keys(state_dict):\n            raise NotAMatchError(\"state dict does not look like a Qwen3 model\")\n        # Reject T5 encoders: they share the token_embd.weight key with Qwen3 GGUFs but use the ``enc.``\n        # block prefix, and must be classified as T5Encoder (Qwen3 encoders never have ``enc.blk.*`` keys).\n        if _has_t5_encoder_keys(state_dict):\n            raise NotAMatchError(\"state dict looks like a T5 encoder (has 'enc.blk.*' keys), not a Qwen3 encoder\")\n        # Reject Gemma-2/3 encoders: their GGUFs also carry token_embd.weight + blk.* keys but use\n        # post-attention / post-feedforward norms a Qwen3 encoder never has; they must be classified as\n        # Gemma2Encoder (otherwise a Gemma GGUF matches both configs and can be re-identified wrongly).\n        if _has_gemma2_keys(state_dict):\n            raise NotAMatchError(\n                \"state dict looks like a Gemma-2 encoder (has post_attention_norm/post_ffw_norm keys), \"\n                \"not a Qwen3 encoder\"","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/configs/qwen3_encoder.py#L208-L244","documentation":"For Qwen3 text-encoder GGUF files, InvokeAI infers the variant (e.g. 0.6B/1.7B/4B/8B) from the hidden size of the embedding tensor. If the state dict's hidden size matches no known Qwen3 variant, `NotAMatchError` is raised — deliberately, because defaulting to 4B caused unrelated causal-LM GGUFs (Mistral, Llama) sharing llama.cpp naming to be misidentified as Qwen3.","triggerScenarios":"`_get_variant_or_default` in `from_model_on_disk` calls `_get_qwen3_variant_from_state_dict`, which returns None because the tensor hidden dimension isn't any Qwen3 size — commonly for non-Qwen3 GGUF LLMs or quantization layouts that change dims.","commonSituations":"Installing a Mistral/Llama GGUF that the router offered to the Qwen3 encoder config; an unusual Qwen3 fine-tune with modified hidden size; mislabeled GGUF file.","solutions":["Confirm the GGUF is actually a Qwen3 model; if it is Mistral/Llama, it is not a Qwen3 encoder and will not match — install it as the correct model type","Re-download an official Qwen3 GGUF release whose hidden size matches a known variant","Check the file isn't corrupted or partially converted; re-quantize/convert from the original safetensors","Upgrade InvokeAI in case newer Qwen3 variants were added to the recognized-size table"],"exampleFix":"// before: mistral-7b.Q4_K_M.gguf offered to qwen3 encoder config -> NotAMatchError\n// after: use the correct model type/source for Mistral GGUFs;\n// or verify Qwen3:\n# hidden size from gguf metadata should match a known Qwen3 variant\n","handlingStrategy":"try-catch","validationCode":"# read gguf hidden size before install\nimport gguf\nr = gguf.GGUFReader(path)\nhidden = r.get_tensor('token_embd.weight').shape[-1]\nKNOWN_QWEN3_HIDDEN = {1024, 2048, 2560, 4096, 5120}  # variant-dependent\nif hidden not in KNOWN_QWEN3_HIDDEN:\n    raise SystemExit('Hidden size does not match a known Qwen3 variant; not a Qwen3 GGUF.')","typeGuard":"def is_qwen3_sized_gguf(hidden_size: int) -> bool:\n    return hidden_size in {1024, 2048, 2560, 4096, 5120}","tryCatchPattern":"try:\n    install_model(path)\nexcept NotAMatchError as e:\n    if 'known Qwen3 variant' in str(e):\n        logger.error('Not a recognizable Qwen3 GGUF (may be Mistral/Llama): %s', e)\n    else:\n        raise","preventionTips":["Verify GGUF architecture metadata (general.architecture == qwen3) before install","Install Mistral/Llama GGUFs as their own model type, not as Qwen3 encoders","Use official Qwen3 GGUF releases with standard hidden sizes","Keep InvokeAI updated for newly recognized Qwen3 variants"],"tags":["gguf","model-identification","qwen3","variant-detection"],"backgroundTag":"model-not-a-match","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}