invoke-ai/InvokeAI · error · ValueError

Only Main_SDNQ_ZImage_Config or Main_SDNQ_Diffusers_ZImage_C

Error message

Only Main_SDNQ_ZImage_Config or Main_SDNQ_Diffusers_ZImage_Config models are supported here.

What it means

The SDNQ Z-Image loader accepts only Main_SDNQ_ZImage_Config (single-file SDNQ checkpoint) or Main_SDNQ_Diffusers_ZImage_Config (full ZImagePipeline folder). Any other config type raises this ValueError. SDNQ quantized weights need their specialized loading path, so foreign configs are rejected up front.

Source

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


@ModelLoaderRegistry.register(base=BaseModelType.ZImage, type=ModelType.Main, format=ModelFormat.SDNQQuantized)
class ZImageSDNQCheckpointModel(ModelLoader):
    """Class to load SDNQ-quantized Z-Image transformer models.

    Handles both single-file SDNQ checkpoints (``Main_SDNQ_ZImage_Config``) and full
    diffusers-pipeline folders (``Main_SDNQ_Diffusers_ZImage_Config``), where the
    quantized weights live under ``transformer/`` alongside a ``config.json`` that
    describes the architecture.
    """

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

        # Single-file SDNQ checkpoints only carry the transformer.
        if isinstance(config, Main_SDNQ_ZImage_Config):
            if submodel_type == SubModelType.Transformer:
                return self._load_from_singlefile(config)
            raise ValueError(
                f"Single-file SDNQ Z-Image checkpoints only provide the Transformer submodel. "
                f"Received: {submodel_type.value if submodel_type else 'None'}"
            )

        # Full ZImagePipeline folder — dispatch each submodel out of its own subfolder so the
        # model can be used as a 'Qwen3 & VAE source model' for other Z-Image runs.
        match submodel_type:
            case SubModelType.Transformer:
                return self._load_from_diffusers_folder(config)
            case SubModelType.TextEncoder:

View on GitHub (pinned to 0b6a024f2f)

Solutions

Re-register the model with the correct SDNQ config class matching the on-disk layout (single file vs pipeline folder).
If the model is not quantized with SDNQ, use the checkpoint or GGUF loader instead.
Check the loader-routing/match code to see why the SDNQ loader was chosen for this config.
In custom code, gate on isinstance(config, (Main_SDNQ_ZImage_Config, Main_SDNQ_Diffusers_ZImage_Config)) before calling.

Example fix

// before
config = Main_Checkpoint_ZImage_Config(path=p)
model = sdnq_loader._load_model(config, SubModelType.Transformer)  # ValueError
// after
config = Main_SDNQ_ZImage_Config(path=p)  # SDNQ single-file checkpoint
model = sdnq_loader._load_model(config, SubModelType.Transformer)

Defensive patterns

Strategy: type-guard

Validate before calling

from invokeai.backend.model_manager.load.model_loaders.z_image import Main_SDNQ_ZImage_Config, Main_SDNQ_Diffusers_ZImage_Config
if not isinstance(config, (Main_SDNQ_ZImage_Config, Main_SDNQ_Diffusers_ZImage_Config)):
    raise ValueError(f"SDNQ loader requires an SDNQ ZImage config, got {type(config).__name__}")

Type guard

def is_zimage_sdnq_config(config: AnyModelConfig) -> bool:
    return isinstance(config, (Main_SDNQ_ZImage_Config, Main_SDNQ_Diffusers_ZImage_Config))

Try / catch

try:
    model = sdnq_loader._load_model(config, submodel_type)
except ValueError as e:
    if "Main_SDNQ_ZImage_Config" in str(e):
        model = select_loader_for(config)._load_model(config, submodel_type)
    else:
        raise

Prevention

Match the config class to the on-disk layout: single SDNQ file vs full pipeline folder.
Let the loader registry pick loaders rather than hard-coding loader classes.
Validate quantization format at model-install time.

When it happens

Trigger: Calling this loader's _load_model with a config that is neither Main_SDNQ_ZImage_Config nor Main_SDNQ_Diffusers_ZImage_Config — e.g. a checkpoint or GGUF config — triggers the ValueError at z_image.py:593.

Common situations: An SDNQ-quantized model was registered with the wrong config class in the model manager; loader matching selected the SDNQ loader for a non-SDNQ model; custom install pipelines instantiate the loader with generic configs.

Related errors

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