invoke-ai/InvokeAI · error · ValueError

Got {params.axes_dim} but expected positional dim {pe_dim}

Error message

Got {params.axes_dim} but expected positional dim {pe_dim}

What it means

After checking head divisibility, XLabsControlNetFlux.__init__ derives pe_dim = hidden_size // num_heads and requires sum(params.axes_dim) — the total rotary-embedding dimension across axes — to equal pe_dim. Mismatched axes_dim means the EmbedND positional embedder would produce embeddings incompatible with the attention head dim, so init fails.

Source

Thrown at invokeai/backend/flux/controlnet/xlabs_controlnet_flux.py:39

    """A ControlNet model for FLUX.

    The architecture is very similar to the base FLUX model, with the following differences:
    - A `controlnet_depth` parameter is passed to control the number of double_blocks that the ControlNet is applied to.
      In order to keep the ControlNet small, this is typically much less than the depth of the base FLUX model.
    - There is a set of `controlnet_blocks` that are applied to the output of each double_block.
    """

    def __init__(self, params: FluxParams, controlnet_depth: int = 2):
        super().__init__()

        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 = torch.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 torch.nn.Identity()
        )
        self.txt_in = torch.nn.Linear(params.context_in_dim, self.hidden_size)

        self.double_blocks = torch.nn.ModuleList(
            [
                DoubleStreamBlock(
                    self.hidden_size,
                    self.num_heads,
                    mlp_ratio=params.mlp_ratio,
                    qkv_bias=params.qkv_bias,

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Set axes_dim so its sum equals hidden_size // num_heads (stock Flux: [16,56,56] for pe_dim=128).
2. Recompute axes_dim proportionally if you change hidden_size or num_heads.
3. Load params from the checkpoint's official config instead of hand-building FluxParams.
4. Assert sum(params.axes_dim) == params.hidden_size // params.num_heads in setup code to fail fast with a clearer message.

Example fix

// before
FluxParams(hidden_size=2048, num_heads=16, axes_dim=[16,56,56])  # pe_dim=128 != sum=128? -> ensure: 2048/16=128 OK; bad case: num_heads=32 → pe_dim=64
// after
FluxParams(hidden_size=2048, num_heads=16, axes_dim=[16,56,56])  # 2048//16 = 128 == 16+56+56

pe_dim = params.hidden_size // params.num_heads
assert params.hidden_size % params.num_heads == 0
assert sum(params.axes_dim) == pe_dim, f"axes_dim sum {sum(params.axes_dim)} != pe_dim {pe_dim}"

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

try:
    controlnet = XLabsControlNetFlux(params=params)
except ValueError as e:
    if "expected positional dim" in str(e):
        params = replace(params, axes_dim=rescale_axes(params.axes_dim, params.hidden_size // params.num_heads))
        controlnet = XLabsControlNetFlux(params=params)
    else:
        raise

When it happens

Trigger: Constructing XLabsControlNetFlux where sum(params.axes_dim) != params.hidden_size // params.num_heads — typically default axes_dim=[16,56,56] (128) paired with a modified hidden_size/num_heads giving a different pe_dim.

Common situations: Scaling hidden_size for a custom model while keeping stock axes_dim; porting XLabs IP-Adapter/ControlNet configs onto a differently-shaped Flux backbone; typos in config files (e.g. axes_dim=[16,56] summing to 72).

Related errors

• Got {params.axes_dim} but expected positional dim {pe_dim}
• Hidden size {params.hidden_size} must be divisible by num_he
• Unsupported cfg_scale type: {type(cfg_scale)}
• Invalid cfg_scale_start_step. Out of range: {cfg_scale_start
• Invalid cfg_scale_end_step. Out of range: {cfg_scale_end_ste

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