{"record":{"id":"2a110e20942e9123","repo":"invoke-ai/InvokeAI","slug":"got-params-axes-dim-but-expected-positional-dim-2a110e","errorCode":null,"errorMessage":"Got {params.axes_dim} but expected positional dim {pe_dim}","messagePattern":"Got (.+?) but expected positional dim (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/flux/model.py","lineNumber":57,"sourceCode":"    out_channels: Optional[int] = None\n\n\nclass Flux(nn.Module):\n    \"\"\"\n    Transformer model for flow matching on sequences.\n    \"\"\"\n\n    def __init__(self, params: FluxParams):\n        super().__init__()\n\n        self.params = params\n        self.in_channels = params.in_channels\n        self.out_channels = params.out_channels or self.in_channels\n        if params.hidden_size % params.num_heads != 0:\n            raise ValueError(f\"Hidden size {params.hidden_size} must be divisible by num_heads {params.num_heads}\")\n        pe_dim = params.hidden_size // params.num_heads\n        if sum(params.axes_dim) != pe_dim:\n            raise ValueError(f\"Got {params.axes_dim} but expected positional dim {pe_dim}\")\n        self.hidden_size = params.hidden_size\n        self.num_heads = params.num_heads\n        self.pe_embedder = EmbedND(dim=pe_dim, theta=params.theta, axes_dim=params.axes_dim)\n        self.img_in = nn.Linear(self.in_channels, self.hidden_size, bias=True)\n        self.time_in = MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size)\n        self.vector_in = MLPEmbedder(params.vec_in_dim, self.hidden_size)\n        self.guidance_in = (\n            MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size) if params.guidance_embed else nn.Identity()\n        )\n        self.txt_in = nn.Linear(params.context_in_dim, self.hidden_size)\n\n        self.double_blocks = nn.ModuleList(\n            [\n                DoubleStreamBlock(\n                    self.hidden_size,\n                    self.num_heads,\n                    mlp_ratio=params.mlp_ratio,\n                    qkv_bias=params.qkv_bias,","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/flux/model.py#L39-L75","documentation":"After computing pe_dim = hidden_size // num_heads, Flux's __init__ requires that the positional-embedding axis dims (axes_dim) sum exactly to pe_dim, because EmbedND splits each head's positional embedding across the configured axes. A mismatch means the rotary positional embedding would have the wrong dimensionality, so construction fails.","triggerScenarios":"Constructing the Flux model with FluxParams whose axes_dim list does not sum to hidden_size/num_heads — e.g. axes_dim=[128,128,128] (sum 384) with pe_dim 128, or adding/removing an axis entry for a custom layout without rebalancing.","commonSituations":"Custom multi-resolution / multi-axis positional encoding experiments; copying axes_dim from FLUX dev (16,56,56 for pe_dim 128) into a model with different hidden_size/num_heads; typos when transcribing params.","solutions":["Make sum(axes_dim) equal hidden_size // num_heads (standard FLUX: [16, 56, 56] summing to 128)","Derive axes_dim programmatically from pe_dim instead of hardcoding","Use the predefined params from get_flux_transformers_params(variant)"],"exampleFix":"// before\npe_dim = params.hidden_size // params.num_heads  # 128\naxes_dim = [128, 128, 128]  # sums to 384 != 128\n// after\npe_dim = params.hidden_size // params.num_heads  # 128\naxes_dim = [16, 56, 56]  # sums to 128","handlingStrategy":"validation","validationCode":"pe_dim = params.hidden_size // params.num_heads\nassert sum(params.axes_dim) == pe_dim, f\"sum(axes_dim)={sum(params.axes_dim)} != pe_dim={pe_dim}\"","typeGuard":"def has_valid_axes_dim(params) -> bool:\n    return sum(params.axes_dim) == params.hidden_size // params.num_heads","tryCatchPattern":"try:\n    model = Flux(params)\nexcept ValueError as e:\n    if \"expected positional dim\" in str(e):\n        pe_dim = params.hidden_size // params.num_heads\n        params.axes_dim = split_evenly(pe_dim, len(params.axes_dim))\n        model = Flux(params)\n    else:\n        raise","preventionTips":["Compute axes_dim from pe_dim rather than hardcoding","Keep the canonical FLUX layout [16, 56, 56] for pe_dim=128","Test sum(axes_dim) == hidden_size // num_heads in config validation"],"tags":["flux","config-validation","positional-embedding","model-init"],"backgroundTag":"model-config-validation","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}