invoke-ai/InvokeAI · error · ValueError

Unsupported submodel type for SDNQ ZImagePipeline

Error message

Unsupported submodel type for SDNQ ZImagePipeline: {submodel_type.value if submodel_type else 'None'}

What it means

For Main_SDNQ_Diffusers_ZImage_Config (full pipeline folder), _load_model dispatches TextEncoder, Tokenizer and VAE submodels; Transformer on folder configs and any other submodel type falls through to this ValueError. It signals the requested submodel cannot be served from the SDNQ ZImagePipeline folder layout.

Solutions

Load the transformer from the single-file SDNQ checkpoint (Main_SDNQ_ZImage_Config) and use the folder model only for TextEncoder/Tokenizer/VAE.
Only request TextEncoder, Tokenizer, or VAE from the SDNQ pipeline-folder loader.
Adjust the pipeline configuration so each submodel points at a model that actually provides it.
Skip Scheduler/other probes for this loader in caller code.

Example fix

// before
transformer = sdnq_loader._load_model(folder_config, SubModelType.Transformer)  # ValueError
// after
transformer = sdnq_loader._load_model(single_file_config, SubModelType.Transformer)
vae = sdnq_loader._load_model(folder_config, SubModelType.VAE)

Defensive patterns

Strategy: validation

Validate before calling

if isinstance(config, Main_SDNQ_Diffusers_ZImage_Config) and submodel_type not in (SubModelType.TextEncoder, SubModelType.Tokenizer, SubModelType.VAE):
    raise ValueError("SDNQ ZImagePipeline folder provides only TextEncoder, Tokenizer and VAE submodels")

Type guard

def folder_sdnq_supports(submodel_type: SubModelType | None) -> bool:
    return submodel_type in (SubModelType.TextEncoder, SubModelType.Tokenizer, SubModelType.VAE)

Try / catch

try:
    model = sdnq_loader._load_model(folder_config, submodel_type)
except ValueError as e:
    if "Unsupported submodel type for SDNQ ZImagePipeline" in str(e):
        model = single_file_loader._load_model(single_file_config, submodel_type)
    else:
        raise

Prevention

Point the pipeline's transformer at the single-file SDNQ checkpoint and the folder model only for TE/tokenizer/VAE.
Map each SubModelType to the model entry that actually contains it before loading.
Avoid scheduler/other probes on this loader.

When it happens

Trigger: Calling _load_model with Main_SDNQ_Diffusers_ZImage_Config and submodel_type equal to Transformer (folder path), Scheduler, or None — anything not handled by the TextEncoder/Tokenizer/VAE cases reaches z_image.py:618.

Common situations: Code requests the transformer from the pipeline-folder model even though the single-file SDNQ checkpoint supplies it; scheduler probes hit a loader without scheduler support; generic submodel iteration requests unsupported types.

Related errors

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

Appendix: source

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

                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'}"
        )

    def _load_text_encoder(self, config: Main_SDNQ_Diffusers_ZImage_Config) -> AnyModel:
        from transformers import AutoConfig, Qwen3ForCausalLM

        te_dir = resolve_submodel_path(config, SubModelType.TextEncoder, Path(config.path) / "text_encoder")
        target_device = TorchDevice.choose_torch_device()
        compute_dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)

        te_config = AutoConfig.from_pretrained(te_dir, local_files_only=True)
        with accelerate.init_empty_weights():
            model = Qwen3ForCausalLM(te_config)

        sd = sdnq_sd_loader(te_dir, compute_dtype=compute_dtype)
        # Qwen3ForCausalLM may share lm_head.weight with model.embed_tokens.weight; missing keys
        # for that tie are expected and handled by re-sharing post-load.
        missing, unexpected = model.load_state_dict(sd, assign=True, strict=False)

View on GitHub (pinned to 0b6a024f2f)