invoke-ai/InvokeAI · error · ValueError

Hidden size {params.hidden_size} must be divisible by num_he

Error message

Hidden size {params.hidden_size} must be divisible by num_heads {params.num_heads}

What it means

Flux model __init__ validates that hidden_size is evenly divisible by num_heads before computing per-head dimensions. If hidden_size % num_heads != 0, the multi-head attention head dimension would be fractional, so construction is aborted with a ValueError. This is a model-configuration sanity check mirroring the original FLUX reference implementation.

Source

Thrown at invokeai/backend/flux/model.py:54

    theta: int
    qkv_bias: bool
    guidance_embed: bool
    out_channels: Optional[int] = None


class Flux(nn.Module):
    """
    Transformer model for flow matching on sequences.
    """

    def __init__(self, params: FluxParams):
        super().__init__()

        self.params = params
        self.in_channels = params.in_channels
        self.out_channels = params.out_channels or self.in_channels
        if params.hidden_size % params.num_heads != 0:
            raise ValueError(f"Hidden size {params.hidden_size} must be divisible by num_heads {params.num_heads}")
        pe_dim = params.hidden_size // params.num_heads
        if sum(params.axes_dim) != pe_dim:
            raise ValueError(f"Got {params.axes_dim} but expected positional dim {pe_dim}")
        self.hidden_size = params.hidden_size
        self.num_heads = params.num_heads
        self.pe_embedder = EmbedND(dim=pe_dim, theta=params.theta, axes_dim=params.axes_dim)
        self.img_in = nn.Linear(self.in_channels, self.hidden_size, bias=True)
        self.time_in = MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size)
        self.vector_in = MLPEmbedder(params.vec_in_dim, self.hidden_size)
        self.guidance_in = (
            MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size) if params.guidance_embed else nn.Identity()
        )
        self.txt_in = nn.Linear(params.context_in_dim, self.hidden_size)

        self.double_blocks = nn.ModuleList(
            [
                DoubleStreamBlock(
                    self.hidden_size,

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Set hidden_size to a multiple of num_heads (FLUX default: hidden_size=3072, num_heads=24, giving pe_dim=128)
2. Use get_flux_transformers_params(variant) from invokeai/backend/flux/util.py instead of hand-rolling FluxParams
3. If you need a custom width, change num_heads so hidden_size % num_heads == 0 and verify sum(axes_dim) equals hidden_size // num_heads

Example fix

// before
params = FluxParams(in_channels=64, hidden_size=3000, num_heads=24, axes_dim=[128,128,128], ...)
// after
params = FluxParams(in_channels=64, hidden_size=3072, num_heads=24, axes_dim=[128,128,128], ...)

assert params.hidden_size % params.num_heads == 0, f"hidden_size {params.hidden_size} not divisible by num_heads {params.num_heads}"

def is_valid_flux_head_config(params) -> bool:
    return params.hidden_size % params.num_heads == 0

try:
    model = Flux(params)
except ValueError as e:
    if "divisible by num_heads" in str(e):
        params.num_heads = pick_num_heads_dividing(params.hidden_size)
        model = Flux(params)
    else:
        raise

When it happens

Trigger: Constructing Flux (or Flux2) model with FluxParams where hidden_size is not a multiple of num_heads, e.g. copying a config and editing hidden_size manually, or loading a variant whose params dict was modified.

Common situations: Hand-edited config JSON/YAML for a custom FLUX variant; porting state dicts from forks with mismatched param blocks; typo in hidden_size (e.g. 3072 vs 3073) while num_heads stays at 24.

Related errors

• Got {params.axes_dim} but expected positional dim {pe_dim}
• `encoder_hid_dim` has to be defined when `encoder_hid_dim_ty
• User not found or inactive
• Missing authentication credentials
• Invalid or expired authentication token

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