{"record":{"id":"005cd88395d95a14","repo":"sgl-project/sglang","slug":"got-axes-dim-but-expected-positional-dim-pe-dim","errorCode":null,"errorMessage":"Got {axes_dim} but expected positional dim {pe_dim}","messagePattern":"Got (.+?) but expected positional dim (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d.py","lineNumber":527,"sourceCode":"        self.num_heads = num_heads\n        self.num_attention_heads = num_heads\n        self.depth = depth\n        self.depth_single_blocks = depth_single_blocks\n        self.axes_dim = axes_dim\n        self.theta = theta\n        self.qkv_bias = qkv_bias\n        self.time_factor = time_factor\n        self.out_channels = self.in_channels\n        self.num_channels_latents = self.in_channels\n        self.guidance_embed = guidance_embed\n\n        if hidden_size % num_heads != 0:\n            raise ValueError(\n                f\"Hidden size {hidden_size} must be divisible by num_heads {num_heads}\"\n            )\n        pe_dim = hidden_size // num_heads\n        if sum(axes_dim) != pe_dim:\n            raise ValueError(f\"Got {axes_dim} but expected positional dim {pe_dim}\")\n        self.latent_in = nn.Linear(self.in_channels, self.hidden_size, bias=True)\n        self.time_in = _FluxMLPEmbedder(in_dim=256, hidden_dim=self.hidden_size)\n        self.cond_in = nn.Linear(context_in_dim, self.hidden_size)\n        self.guidance_in = (\n            _FluxMLPEmbedder(in_dim=256, hidden_dim=self.hidden_size)\n            if guidance_embed\n            else nn.Identity()\n        )\n\n        self.double_blocks = nn.ModuleList(\n            [\n                _FluxDoubleStreamBlock(\n                    self.hidden_size,\n                    self.num_heads,\n                    mlp_ratio=mlp_ratio,\n                    qkv_bias=qkv_bias,\n                    supported_attention_backends=supported_attention_backends,\n                )","sourceCodeStart":509,"sourceCodeEnd":545,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d.py#L509-L545","documentation":"After computing pe_dim = hidden_size // num_heads, the Hunyuan3D transformer requires sum(axes_dim) to equal pe_dim because the rotary/axial position embedding is split across axes and must exactly fill the per-head dimension. This ValueError fires in __init__ when the axes_dim list doesn't sum to that value.","triggerScenarios":"Configuring the model with axes_dim whose total doesn't equal hidden_size//num_heads, e.g. axes_dim=[16,56,32]=104 but pe_dim=72 for hidden_size=1152, num_heads=16.","commonSituations":"Changing num_heads (which changes pe_dim) without updating axes_dim; porting a 2D axes_dim config (two entries) to a 3D model that expects three entries summing differently.","solutions":["Set axes_dim so its entries sum to hidden_size//num_heads (e.g. for pe_dim=72 use [24,24,24])","If you changed num_heads, recompute axes_dim accordingly","Use the axes_dim from the official Hunyuan3D config for the checkpoint you load"],"exampleFix":"# before\naxes_dim=[16, 56, 32]  # sums to 104, pe_dim=72\n\n# after\naxes_dim=[24, 24, 24]  # sums to 72 = 1152//16","handlingStrategy":"validation","validationCode":"pe_dim = hidden_size // num_heads\nassert sum(axes_dim) == pe_dim, f'axes_dim {axes_dim} sums to {sum(axes_dim)}, expected {pe_dim}'","typeGuard":"def axes_dim_valid(axes_dim, hidden_size, num_heads) -> bool:\n    return sum(axes_dim) == hidden_size // num_heads","tryCatchPattern":null,"preventionTips":["Treat rope axes_dim as coupled to hidden_size//num_heads — change them together","Unit-test config invariants before loading weights"],"tags":["config","validation","rope","diffusion"],"backgroundTag":"positional-embedding-dimension-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}