invoke-ai/InvokeAI · error · ValueError

The {model_name} model must be a Diffusers-style Z-Image pip

Error message

The {model_name} model must be a Diffusers-style Z-Image pipeline (with VAE / Qwen3 submodels). The selected model '{config.name}' is in {config.format.value} format.

What it means

_validate_diffusers_format in invokeai/app/invocations/z_image_model_loader.py requires the selected Z-Image model to be a Diffusers-format pipeline containing VAE and Qwen3 text-encoder submodels. Single-file SDNQ Z-Image checkpoints and partial pipelines cannot be loaded by this invocation, so a ValueError is raised naming the model and its actual format. The check passes only when config.format == ModelFormat.Diffusers or the config is a self-contained SDNQ pipeline.

Source

Thrown at invokeai/app/invocations/z_image_model_loader.py:174

        Otherwise we fall through and require an explicit VAE / Qwen3 source."""
        config = context.models.get_config(self.model)
        if is_self_contained_sdnq_pipeline(config):
            return self.model
        return None

    def _validate_diffusers_format(
        self, context: InvocationContext, model: ModelIdentifierField, model_name: str
    ) -> None:
        """Validate that a model exposes the diffusers-style submodel layout (transformer / vae /
        text_encoder / tokenizer subfolders). Plain diffusers Z-Image pipelines satisfy this;
        SDNQ-quantized ZImagePipeline folders do too, but only when they ship the VAE + Qwen3
        submodels. Single-file SDNQ Z-Image checkpoints and partial pipelines are rejected."""
        config = context.models.get_config(model)
        if config.format == ModelFormat.Diffusers:
            return
        if is_self_contained_sdnq_pipeline(config):
            return
        raise ValueError(
            f"The {model_name} model must be a Diffusers-style Z-Image pipeline (with VAE / Qwen3 "
            f"submodels). The selected model '{config.name}' is in {config.format.value} format."
        )

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Convert or download the Z-Image model as a full Diffusers pipeline directory containing VAE and Qwen3 text-encoder submodels.
2. Re-import the model in InvokeAI's model manager selecting the Diffusers format so config.format is correct.
3. If using an SDNQ checkpoint, ensure it is a self-contained pipeline (all submodels embedded) so is_self_contained_sdnq_pipeline accepts it.
4. Verify the model folder contains all required submodel directories (transformer, vae, text_encoder/tokenizer) and re-scan models.

Example fix

// before: single-file SDNQ checkpoint selected
model = "z-image-sdnq-single.safetensors"
// after: full Diffusers pipeline directory
model = "stabilityai/z-image"  # Diffusers format with VAE/Qwen3 submodels

config = context.models.get_config(model)
if config.format != ModelFormat.Diffusers and not is_self_contained_sdnq_pipeline(config):
    raise ValueError(f"{config.name} must be a Diffusers Z-Image pipeline with VAE/Qwen3 submodels (got {config.format.value})")

try:
    loader.invoke(context)
except ValueError as e:
    if "must be a Diffusers-style Z-Image pipeline" in str(e):
        # prompt user to install/convert the model as Diffusers format
        ...
    else:
        raise

When it happens

Trigger: Calling the Z-Image model loader invocation with a model whose ModelConfig format is not ModelFormat.Diffusers (e.g. single-file checkpoint or partial pipeline) and which is not recognized by is_self_contained_sdnq_pipeline(config).

Common situations: User installs a single-file SDNQ Z-Image .safetensors checkpoint or a checkpoint missing VAE/Qwen3 submodel folders; model imported with the wrong format in the model manager; using an older/non-Diffusers conversion of Z-Image.

Related errors

• The {model_name} model must be a Diffusers format model. The
• The {model_name} model must be a Diffusers-style FLUX.2 pipe
• To extract the VAE and Qwen3-VL encoder, the {model_name} mo
• 'Transformer (Low Noise)' must be a single-file Wan model (G
• The Component Source model must be in Diffusers format. The

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