invoke-ai/InvokeAI · error · ValueError

Unknown variant for FLUX transformer params: {variant}

Error message

Unknown variant for FLUX transformer params: {variant}

What it means

get_flux_transformers_params returns the FluxParams configuration for a given FLUX variant from the _flux_transformer_params dict. An unrecognized variant raises ValueError. This is called during model loading (single-file loader, XLabs controlnet, SDNQ checkpoints), so an invalid variant blocks model construction entirely.

Source

Thrown at invokeai/backend/flux/util.py:195

        context_in_dim=12288,  # 3 layers * 4096 = 12288 for Qwen3-8B
        hidden_size=3072,
        mlp_ratio=4.0,
        num_heads=24,
        depth=19,
        depth_single_blocks=38,
        axes_dim=[16, 56, 56],
        theta=10_000,
        qkv_bias=True,
        guidance_embed=False,
    ),
}


def get_flux_transformers_params(variant: AnyVariant):
    try:
        return _flux_transformer_params[variant]
    except KeyError:
        raise ValueError(f"Unknown variant for FLUX transformer params: {variant}")

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Check _flux_transformer_params in invokeai/backend/flux/util.py for supported keys and use one of them
2. Upgrade InvokeAI to a version that supports your FLUX variant
3. Fall back to the closest supported variant's params if the architecture matches
4. Register the new variant in _flux_transformer_params when extending the codebase

Example fix

// before
params = get_flux_transformers_params("flux.2-dev")
// after
params = get_flux_transformers_params("flux-dev")  # supported variant, or upgrade InvokeAI

from invokeai.backend.flux.util import _flux_transformer_params
assert variant in _flux_transformer_params, f"unsupported FLUX variant: {variant}"

try:
    params = get_flux_transformers_params(variant)
except ValueError as e:
    logging.warning("%s — falling back to flux-dev params", e)
    params = get_flux_transformers_params("flux-dev")

When it happens

Trigger: Loading a FLUX checkpoint where the detected/declared variant string is not a key of _flux_transformer_params — e.g. new community variants (kontext, fill, depth, flux2) absent from this InvokeAI version, or misspelled variant in a config/model-manager record.

Common situations: Community fine-tunes labeled with novel variant names; older InvokeAI version encountering newer FLUX releases; variant inference from file metadata returning an unexpected string.

Related errors

• Unknown variant for FLUX max seq len: {variant}
• Admin privileges required
• Expected LlavaOnevisionForConditionalGeneration, got {type(m
• Expected ModelPatchRaw for LoRA '{lora.lora.key}', got {type
• Expected AutoencoderKLWan or FluxAutoEncoder for Anima VAE,

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