{"record":{"id":"2c02190d9210d182","repo":"Comfy-Org/ComfyUI","slug":"got-params-axes-dim-but-expected-positional-dim-2c0219","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":"comfy/ldm/flux/model.py","lineNumber":82,"sourceCode":"    \"\"\"\n    Transformer model for flow matching on sequences.\n    \"\"\"\n\n    def __init__(self, image_model=None, final_layer=True, dtype=None, device=None, operations=None, **kwargs):\n        super().__init__()\n        self.dtype = dtype\n        params = FluxParams(**kwargs)\n        self.params = params\n        self.patch_size = params.patch_size\n        self.in_channels = params.in_channels * params.patch_size * params.patch_size\n        self.out_channels = params.out_channels * params.patch_size * params.patch_size\n        if params.hidden_size % params.num_heads != 0:\n            raise ValueError(\n                f\"Hidden size {params.hidden_size} must be divisible by num_heads {params.num_heads}\"\n            )\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 = operations.Linear(self.in_channels, self.hidden_size, bias=params.ops_bias, dtype=dtype, device=device)\n        self.time_in = MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size, bias=params.ops_bias, dtype=dtype, device=device, operations=operations)\n        if params.vec_in_dim is not None:\n            self.vector_in = MLPEmbedder(params.vec_in_dim, self.hidden_size, dtype=dtype, device=device, operations=operations)\n        else:\n            self.vector_in = None\n\n        self.guidance_in = (\n            MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size, bias=params.ops_bias, dtype=dtype, device=device, operations=operations) if params.guidance_embed else nn.Identity()\n        )\n        self.txt_in = operations.Linear(params.context_in_dim, self.hidden_size, bias=params.ops_bias, dtype=dtype, device=device)\n\n        if params.txt_norm:\n            self.txt_norm = operations.RMSNorm(params.context_in_dim, dtype=dtype, device=device)\n        else:","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy/ldm/flux/model.py#L64-L100","documentation":"After computing pe_dim = hidden_size // num_heads, Flux verifies that the RoPE axes_dim list sums exactly to pe_dim, because each positional axis consumes part of the per-head dimension. A mismatch (sum too large or small) raises ValueError at construction. axes_dim comes from FluxParams and encodes how the head dim is split across (image H, image W, text) axes.","triggerScenarios":"Overriding hidden_size or num_heads without updating axes_dim (e.g. changing hidden_size 3072->1152 while axes_dim stays [16,56,56] summing to 128); or editing axes_dim for a custom rope layout whose sum no longer equals hidden_size // num_heads.","commonSituations":"Porting Flux variants (e.g. different resolutions/rope splits) with partially-updated params; config merges that take axes_dim from one variant and hidden_size/num_heads from another.","solutions":["Make sum(axes_dim) == hidden_size // num_heads; for stock Flux dev/schnell: hidden_size 3072, num_heads 24, axes_dim [16, 56, 56] (sum 128).","When changing hidden_size or num_heads, recompute axes_dim in the same edit — treat the three fields as one unit.","Validate the triple before constructing the model in custom loaders."],"exampleFix":"# before\nFlux(hidden_size=1152, num_heads=24, axes_dim=[16, 56, 56], ...)\n\n# after\nFlux(hidden_size=1152, num_heads=18, axes_dim=[6, 32, 32], ...)  # 1152/18=64=sum(axes_dim)","handlingStrategy":"validation","validationCode":"pe_dim = hidden_size // num_heads\nassert sum(axes_dim) == pe_dim, f\"sum(axes_dim)={sum(axes_dim)} != hidden_size//num_heads={pe_dim}\"","typeGuard":"def valid_flux_axes(hidden_size: int, num_heads: int, axes_dim: list) -> bool:\n    return sum(axes_dim) == hidden_size // num_heads","tryCatchPattern":null,"preventionTips":["Change hidden_size, num_heads, and axes_dim together as one unit.","Add an assert in custom loaders so config drift fails before model construction."],"tags":["flux","rope","config","model-construction"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}