invoke-ai/InvokeAI · error · ValueError

The {model_name} model must be a FLUX.2 [dev] pipeline, but

Error message

The {model_name} model must be a FLUX.2 [dev] pipeline, but the selected model '{config.name}' is variant '{variant.value}'. Its text encoder is incompatible with the [dev] transformer. (Its VAE is compatible - this only blocks encoder extraction.)

What it means

_validate_encoder_source throws this when the Diffusers model used to extract a text encoder is a FLUX.2 Klein pipeline rather than FLUX.2 [dev]. Klein's Qwen3 tokenizer/encoder can silently pass layer-count checks and produce wrong-width conditioning that only fails as an opaque matmul error deep in denoising, so the loader rejects non-[dev] variants early with a clear message. The VAE from Klein is still acceptable; only encoder extraction is blocked.

Source

Thrown at invokeai/app/invocations/flux2_dev_model_loader.py:208

        if config.format != ModelFormat.Diffusers:
            raise ValueError(
                f"The {model_name} model must be a Diffusers format model. "
                f"The selected model '{config.name}' is in {config.format.value} format."
            )
        return config

    def _validate_encoder_source(
        self, context: InvocationContext, model: ModelIdentifierField, model_name: str
    ) -> None:
        """Validate a Diffusers pipeline used as the *text encoder* source."""
        config = self._validate_diffusers_format(context, model, model_name)
        # The source's tokenizer/encoder are extracted and paired with the [dev] transformer.
        # A Klein pipeline's Qwen3 tokenizer + encoder silently pass the layer-count guard and
        # produce a wrong-width conditioning that only surfaces as an opaque matmul error deep in
        # denoise, so reject non-[dev] sources here where the user still gets a clear message.
        variant = getattr(config, "variant", None)
        if variant is not None and variant != Flux2VariantType.Dev:
            raise ValueError(
                f"The {model_name} model must be a FLUX.2 [dev] pipeline, "
                f"but the selected model '{config.name}' is variant '{variant.value}'. "
                "Its text encoder is incompatible with the [dev] transformer. "
                "(Its VAE is compatible - this only blocks encoder extraction.)"
            )

View on GitHub (pinned to 0b6a024f2f)

Solutions

Point the 'Mistral Source' input at a FLUX.2 [dev] Diffusers pipeline (variant 'dev').
If only the VAE was needed from this source, keep the Klein pipeline for the VAE but supply the encoder via a standalone 'Mistral Encoder' input instead.

Example fix

// before
mistral_source = flux2_klein_4b_pipeline  // variant: klein
// after
mistral_source = flux2_dev_pipeline  // variant: dev

Defensive patterns

Strategy: validation

Validate before calling

config = context.models.get_config(model)
variant = getattr(config, "variant", None)
if variant is not None and variant != Flux2VariantType.Dev:
    raise ValueError(f"Encoder source '{config.name}' is variant '{variant.value}', not dev")

Type guard

def is_flux2_dev(config) -> bool:
    return getattr(config, "variant", None) == Flux2VariantType.Dev

Try / catch

try:
    output = loader.invoke(context)
except ValueError as e:
    if "must be a FLUX.2 [dev] pipeline" in str(e):
        loader.mistral_source_model = select_dev_variant_model(context)
        output = loader.invoke(context)
    else:
        raise

Prevention

Verify the model's variant is 'dev' in the Model Manager before using it as an encoder source.
Klein pipelines are fine for VAE extraction but never for encoder extraction.
Keep dev and Klein models clearly named/segregated to avoid mix-ups.

When it happens

Trigger: _validate_encoder_source is called (via invoke() when 'Mistral Source' supplies the encoder) and getattr(config, 'variant') is a Flux2VariantType other than Flux2VariantType.Dev.

Common situations: A user selects a FLUX.2 Klein (4B/9B) Diffusers pipeline as the 'Mistral Source', assuming any FLUX.2 diffusers model works, when they actually want dev conditioning for the [dev] transformer.

Related errors

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