invoke-ai/InvokeAI · error · ValueError

Only Qwen3Encoder_GGUF_Config models are supported here.

Error message

Only Qwen3Encoder_GGUF_Config models are supported here.

What it means

The Z-Image GGUF text-encoder loader only accepts Qwen3Encoder_GGUF_Config instances. A config of any other type cannot provide the GGUF file path or quantization metadata the loader needs, so _load_model raises this ValueError before attempting any load.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/z_image.py:1167

                    parent.register_buffer(buffer_name, inv_freq.to(model_dtype), persistent=False)
                else:
                    # For other buffers, log warning
                    logger.warning(f"Re-initializing unknown meta buffer: {name}")

        return model


@ModelLoaderRegistry.register(base=BaseModelType.Any, type=ModelType.Qwen3Encoder, format=ModelFormat.GGUFQuantized)
class Qwen3EncoderGGUFLoader(ModelLoader):
    """Class to load GGUF-quantized Qwen3 Encoder models for Z-Image."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if not isinstance(config, Qwen3Encoder_GGUF_Config):
            raise ValueError("Only Qwen3Encoder_GGUF_Config models are supported here.")

        match submodel_type:
            case SubModelType.TextEncoder:
                return self._load_from_gguf(config)
            case SubModelType.Tokenizer:
                # GGUF checkpoints ship no tokenizer files; use the vendored copy.
                return self._load_bundled_tokenizer()

        raise ValueError(
            f"Only TextEncoder and Tokenizer submodels are supported. Received: {submodel_type.value if submodel_type else 'None'}"
        )

    def _load_bundled_tokenizer(self) -> AnyModel:
        """Load the Qwen3 tokenizer from the vendored, bundled copy.

        Single-file / GGUF checkpoints do not ship tokenizer files. The Qwen3 BPE
        tokenizer is identical across the 0.6B / 4B / 8B variants, so we load the
        self-contained copy vendored in the package — fully offline, no HuggingFace

View on GitHub (pinned to 0b6a024f2f)

Solutions

Re-register the model as GGUF format so InvokeAI creates a Qwen3Encoder_GGUF_Config for it.
If the file is actually a plain safetensors checkpoint, use the checkpoint loader (error index 1332 path) instead.
Construct a Qwen3Encoder_GGUF_Config explicitly when calling the loader programmatically.
Check the model's format field in the model manager and correct it to match the on-disk file.

Example fix

// before (checkpoint config reaching GGUF loader)
config = Qwen3Encoder_Checkpoint_Config(path="encoder.gguf")
// after
config = Qwen3Encoder_GGUF_Config(path="encoder.gguf")
loader._load_model(config, submodel_type=SubModelType.TextEncoder)

Defensive patterns

Strategy: type-guard

Validate before calling

if not isinstance(config, Qwen3Encoder_GGUF_Config):
    raise TypeError(f"GGUF loader needs Qwen3Encoder_GGUF_Config, got {type(config).__name__}")

Type guard

def is_qwen3_gguf_config(config: AnyModelConfig) -> bool:
    return isinstance(config, Qwen3Encoder_GGUF_Config)

Try / catch

try:
    model = loader._load_model(config, submodel_type)
except ValueError as e:
    if "Qwen3Encoder_GGUF_Config" in str(e):
        config = re_register_model_as_gguf(model_id)
        model = loader._load_model(config, submodel_type)
    else:
        raise

Prevention

Register GGUF files with format=GGUF so the GGUF config class is created.
Don't reuse checkpoint configs for GGUF files after swapping files.
Re-scan the model directory after changing file formats.
Verify the file magic/extension before choosing a loader.

When it happens

Trigger: GGUF loader dispatched with a checkpoint-format config (Qwen3Encoder_Checkpoint_Config or generic), or a script calls _load_model with a manually built config that is not Qwen3Encoder_GGUF_Config.

Common situations: Model file is GGUF but the record was registered as single-file checkpoint; user swapped the file extension/format after registration without re-scanning; custom automation passing configs between the checkpoint and GGUF loaders.

Related errors

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