{"record":{"id":"c7b99d02b150395f","repo":"hpcaitech/Open-Sora","slug":"got-config-axes-dim-but-expected-positional-dim","errorCode":null,"errorMessage":"Got {config.axes_dim} but expected positional dim {pe_dim}","messagePattern":"Got (.+?) but expected positional dim (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"opensora/models/mmdit/model.py","lineNumber":87,"sourceCode":"class MMDiTModel(nn.Module):\n    config_class = MMDiTConfig\n\n    def __init__(self, config: MMDiTConfig):\n        super().__init__()\n\n        self.config = config\n        self.in_channels = config.in_channels\n        self.out_channels = self.in_channels\n        self.patch_size = config.patch_size\n\n        if config.hidden_size % config.num_heads != 0:\n            raise ValueError(\n                f\"Hidden size {config.hidden_size} must be divisible by num_heads {config.num_heads}\"\n            )\n\n        pe_dim = config.hidden_size // config.num_heads\n        if sum(config.axes_dim) != pe_dim:\n            raise ValueError(\n                f\"Got {config.axes_dim} but expected positional dim {pe_dim}\"\n            )\n\n        self.hidden_size = config.hidden_size\n        self.num_heads = config.num_heads\n        pe_embedder_cls = LigerEmbedND if config.use_liger_rope else EmbedND\n        self.pe_embedder = pe_embedder_cls(\n            dim=pe_dim, theta=config.theta, axes_dim=config.axes_dim\n        )\n\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(config.vec_in_dim, self.hidden_size)\n        self.guidance_in = (\n            MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size)\n            if config.guidance_embed\n            else nn.Identity()\n        )","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/hpcaitech/Open-Sora/blob/7ad6a96a135feb81f755c84fb391818718f6beb2/opensora/models/mmdit/model.py#L69-L105","documentation":"Immediately after the divisibility check, MMDiT verifies that sum(config.axes_dim) equals pe_dim = hidden_size // num_heads, because the N-D rotary embedding (EmbedND/LigerEmbedND) allocates rope dims per axis and they must exactly fill the head dimension. A mismatch means rotary embeddings would be truncated or oversized.","triggerScenarios":"Configuring rope axes_dim (e.g. [16, 24, 24] for t/h/w) whose sum does not equal hidden_size // num_heads; changing num_heads or hidden_size without updating axes_dim (or vice versa).","commonSituations":"Porting a config between MMDiT sizes (e.g. from a 2-axis image model to 3-axis video), editing head counts, or hand-writing rope configs.","solutions":["Compute axes_dim as a partition of hidden_size // num_heads (e.g. pe_dim=64 → [16, 24, 24])","If you changed num_heads/hidden_size, rescale axes_dim entries to sum to the new pe_dim","Use symmetric spatial dims (h/w equal) unless the task requires otherwise; only the SUM is validated"],"exampleFix":"# before\n# hidden_size=3072, num_heads=24 → pe_dim=128, axes_dim=[16, 56, 56] (sum=128) ok;\nconfig.axes_dim = [16, 32, 32]  # sum=80 ≠ 128 → error\n# after\nconfig.axes_dim = [16, 56, 56]  # sum == 3072 // 24\nmodel = MMDit(config)","handlingStrategy":"validation","validationCode":"pe_dim = config.hidden_size // config.num_heads\nassert sum(config.axes_dim) == pe_dim, f\"axes_dim sums to {sum(config.axes_dim)}, need {pe_dim}\"","typeGuard":"def is_valid_axes_dim(axes_dim, hidden_size, num_heads) -> bool:\n    return sum(axes_dim) == hidden_size // num_heads","tryCatchPattern":null,"preventionTips":["Derive axes_dim from hidden_size//num_heads instead of hardcoding","Re-validate rope config after any head-count change","Keep h/w rope dims equal for square video patches"],"tags":["transformer","mmdit","rope","config"],"backgroundTag":"rope-axes-dim-mismatch","analyzedSha":"7ad6a96a135feb81f755c84fb391818718f6beb2","analyzedAt":"2026-08-28T16:58:37.171Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}