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

InstantX ControlNet FLUX mirrors the base FLUX transformer: attention head dimension is derived as hidden_size // num_heads. If hidden_size isn't divisible by num_heads, head splitting is impossible, so __init__ raises ValueError during module construction.

Source

Thrown at invokeai/backend/flux/controlnet/instantx_controlnet_flux.py:56


class InstantXControlNetFlux(torch.nn.Module):
    def __init__(self, params: FluxParams, num_control_modes: int | None = None):
        """
        Args:
            params (FluxParams): The parameters for the FLUX model.
            num_control_modes (int | None, optional): The number of controlnet modes. If non-None, then the model is a
                'union controlnet' model and expects a mode conditioning input at runtime.
        """
        super().__init__()

        # The following modules mirror the base FLUX transformer model.
        # -------------------------------------------------------------
        self.params = params
        self.in_channels = params.in_channels
        self.out_channels = 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

Fix the config so hidden_size is divisible by num_heads (use the base FLUX values, e.g. hidden_size=3072, num_heads=24).
Copy params from the matching base FLUX transformer checkpoint rather than hand-authoring them.
Add a pre-construction config validation asserting hidden_size % num_heads == 0.

Example fix

// before
params = FluxParams(hidden_size=1280, num_heads=12, ...)
model = FluxControlNetInstantXModel(params)  # raises
// after
params = FluxParams(hidden_size=3072, num_heads=24, ...)
model = FluxControlNetInstantXModel(params)

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

def is_valid_flux_params(params) -> bool:
    return params.hidden_size % params.num_heads == 0 and sum(params.axes_dim) == params.hidden_size // params.num_heads

Try / catch

try:
    model = FluxControlNetInstantXModel(params)
except ValueError as e:
    if "divisible by num_heads" in str(e):
        logger.error("Bad FLUX config: %s", e)
    raise

Prevention

Copy FluxParams from the loaded base transformer instead of hand-authoring configs.
Add a config lint that checks divisibility and axes_dim consistency.
Version-control known-good model configs per FLUX variant.

When it happens

Trigger: Constructing FluxControlNetInstantXModel(params) with a FluxParams whose hidden_size % num_heads != 0, e.g. hidden_size=1280, num_heads=12.

Common situations: Hand-written model configs (YAML/JSON) mixing values from different FLUX variants; typos in hidden_size or num_heads; loading a config saved for another architecture into this class.

Related errors

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