Comfy-Org/ComfyUI · error · ValueError

Hidden size {params.hidden_size} must be divisible by num_he

Error message

Hidden size {params.hidden_size} must be divisible by num_heads {params.num_heads}

What it means

Same divisibility invariant as other DiT transformers but for HunyuanVideo: params.hidden_size must be divisible by params.num_heads at construction. HunyuanVideoParams is built from **kwargs, so any config key mismatch or typo silently becomes a wrong default and can trip this check.

Source

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

class HunyuanVideo(nn.Module):
    """
    Transformer model for flow matching on sequences.
    """

    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()

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Use the checkpoint's original config mapping (all key names must match HunyuanVideoParams fields exactly)
2. Set num_heads to hidden_size // 128 (typical head_dim) or another exact divisor
3. Validate the kwargs dict before construction: hidden_size % num_heads == 0

Example fix

# before: typo leaves num_heads at default
model = HunyuanVideoTransformer(num_head=24, hidden_size=3072)
# after
model = HunyuanVideoTransformer(num_heads=24, hidden_size=3072)

assert kwargs['hidden_size'] % kwargs['num_heads'] == 0

When it happens

Trigger: Constructing HunyuanVideoTransformer with kwargs where hidden_size % num_heads != 0, or where a key name typo (e.g. num_head instead of num_heads) leaves num_heads at a default that does not divide the supplied hidden_size.

Common situations: Loading a checkpoint whose config JSON was converted with wrong key names, or manually specifying only one of the two fields when instantiating the model.

Related errors

• Hidden size {hidden_size} must be divisible by num_heads {nu
• Got {params.axes_dim} but expected positional dim {pe_dim}
• `only_cross_attention` can only be set to True if `added_kv_
• Hidden size {params.hidden_size} must be divisible by num_he
• Hidden size {params.hidden_size} must be divisible by num_he

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