invoke-ai/InvokeAI · error · ValueError

Single-file SDNQ Z-Image checkpoints only provide the Transf

Error message

Single-file SDNQ Z-Image checkpoints only provide the Transformer submodel. Received: {submodel_type.value if submodel_type else 'None'}

What it means

Single-file SDNQ Z-Image checkpoints physically contain only the transformer weights. When the config is Main_SDNQ_ZImage_Config, _load_model serves only SubModelType.Transformer; any other submodel (or None) raises this ValueError. Folder-based Main_SDNQ_Diffusers_ZImage_Config configs bypass this branch and dispatch all submodels.

Source

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

    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:
                return self._load_text_encoder(config)
            case SubModelType.Tokenizer:
                return self._load_tokenizer(config)
            case SubModelType.VAE:
                return self._load_vae(config)

        raise ValueError(
            f"Unsupported submodel type for SDNQ ZImagePipeline: {submodel_type.value if submodel_type else 'None'}"

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Request only SubModelType.Transformer from the single-file SDNQ model.
2. Register a full SDNQ ZImagePipeline folder (Main_SDNQ_Diffusers_ZImage_Config) or another model as the VAE/text-encoder/tokenizer source and reference it in the pipeline.
3. Update caller logic to check the config type before probing submodels other than Transformer.
4. Convert the single-file checkpoint into a full pipeline folder if all submodels must come from one entry.

Example fix

// before
te = sdnq_loader._load_model(single_file_config, SubModelType.TextEncoder)  # ValueError
// after
transformer = sdnq_loader._load_model(single_file_config, SubModelType.Transformer)
te = sdnq_loader._load_model(folder_config, SubModelType.TextEncoder)  # from pipeline-folder model

if isinstance(config, Main_SDNQ_ZImage_Config) and submodel_type is not SubModelType.Transformer:
    raise ValueError("single-file SDNQ Z-Image checkpoints only provide the Transformer submodel")

def sdnq_provides(config: AnyModelConfig, submodel_type: SubModelType | None) -> bool:
    if isinstance(config, Main_SDNQ_ZImage_Config):
        return submodel_type is SubModelType.Transformer
    return submodel_type in (SubModelType.TextEncoder, SubModelType.Tokenizer, SubModelType.VAE)

try:
    model = sdnq_loader._load_model(config, submodel_type)
except ValueError as e:
    if "only provide the Transformer" in str(e):
        model = companion_loader._load_model(companion_config, submodel_type)
    else:
        raise

When it happens

Trigger: Calling _load_model with a Main_SDNQ_ZImage_Config and submodel_type other than SubModelType.Transformer — e.g. VAE, TextEncoder, Tokenizer — or leaving submodel_type as None; the loader framework probing available submodels.

Common situations: A pipeline install attempts to load the VAE or text encoder from a single-file SDNQ checkpoint; code assumes all SDNQ models are full pipeline folders; submodel auto-discovery iterates every SubModelType against a transformer-only checkpoint.

Related errors

• Unsupported submodel type for SDNQ ZImagePipeline: {submodel
• Only Tokenizer and TextEncoder submodels are supported. Rece
• A submodel type must be provided when loading onnx pipelines
• Unexpected submodel requested for PiD decoder.
• Only Main_SDNQ_ZImage_Config or Main_SDNQ_Diffusers_ZImage_C

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