Comfy-Org/ComfyUI · 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

Raised in the HunyuanVideo constructor when sum(params.axes_dim) does not equal head_dim = hidden_size // num_heads. The RoPE positional embedder (EmbedND) splits head_dim into per-axis frequencies (typically 3 axes for t/h/w), so the axes must exactly tile the head dimension.

Source

Thrown at comfy/ldm/hunyuan_video/model.py:219

    def __init__(self, image_model=None, final_layer=True, dtype=None, device=None, operations=None, **kwargs):
        super().__init__()
        self.dtype = dtype
        operation_settings = {"operations": operations, "device": device, "dtype": dtype}

        params = HunyuanVideoParams(**kwargs)
        self.params = params
        self.patch_size = params.patch_size
        self.in_channels = params.in_channels
        self.out_channels = params.out_channels
        self.use_cond_type_embedding = params.use_cond_type_embedding
        self.vision_in_dim = params.vision_in_dim
        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 = comfy.ldm.modules.diffusionmodules.mmdit.PatchEmbed(None, self.patch_size, self.in_channels, self.hidden_size, conv3d=len(self.patch_size) == 3, dtype=dtype, device=device, operations=operations)
        self.time_in = MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size, dtype=dtype, device=device, operations=operations)
        if params.vec_in_dim is not None:
            self.vector_in = MLPEmbedder(params.vec_in_dim, self.hidden_size, dtype=dtype, device=device, operations=operations)
        else:
            self.vector_in = None

        self.guidance_in = (
            MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size, dtype=dtype, device=device, operations=operations) if params.guidance_embed else nn.Identity()
        )

        self.txt_in = TokenRefiner(params.context_in_dim, self.hidden_size, self.num_heads, 2, dtype=dtype, device=device, operations=operations)

        self.double_blocks = nn.ModuleList(

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Set axes_dim to a 3-way partition of hidden_size // num_heads that sums exactly to head_dim (e.g. head_dim 80 -> (16, 32, 32))
2. Check whether the checkpoint is image (2D) or video (3D) and use its original axes_dim/patch_size pair
3. Recompute: assert sum(axes_dim) == hidden_size // num_heads before building the model

Example fix

# before (2D image axes on a video config)
axes_dim = (16, 112); hidden_size=1280; num_heads=16  # sum 128 != 80
# after (3D video axes)
axes_dim = (16, 32, 32)  # sums to 80 == 1280 // 16

head_dim = params.hidden_size // params.num_heads
assert sum(params.axes_dim) == head_dim, (params.axes_dim, head_dim)

When it happens

Trigger: Constructing the model with a 3D axes_dim like (4,32,32) while hidden_size//num_heads = 128 (sum 64 != 128); or a 2D axes_dim applied to a 3D-patched video config after downgrading patch_size to 2D.

Common situations: Mixing 1.0 (2D image) and 2.1 (3D video) HunyuanVideo configs, hand-editing axes_dim for a different aspect bucketing, or transcribing configs between repos with different theta/axes conventions.

Related errors

• Hidden size {params.hidden_size} must be divisible by num_he
• Got {params.axes_dim} but expected positional dim {pe_dim}
• Got {params.axes_dim} but expected positional dim {pe_dim}
• Unknown interpolation method {self.interpolation}
• Got {params.axes_dim} but expected positional dim {pe_dim}

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/a662153c2bbe0d5e. Report an issue: GitHub.