{"record":{"id":"3a31820cfdcf908c","repo":"Comfy-Org/ComfyUI","slug":"hidden-size-params-hidden-size-must-be-divisible-3a3182","errorCode":null,"errorMessage":"Hidden size {params.hidden_size} must be divisible by num_heads {params.num_heads}","messagePattern":"Hidden size (.+?) must be divisible by num_heads (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy/ldm/hunyuan_video/model.py","lineNumber":214,"sourceCode":"class HunyuanVideo(nn.Module):\n    \"\"\"\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        operation_settings = {\"operations\": operations, \"device\": device, \"dtype\": dtype}\n\n        params = HunyuanVideoParams(**kwargs)\n        self.params = params\n        self.patch_size = params.patch_size\n        self.in_channels = params.in_channels\n        self.out_channels = params.out_channels\n        self.use_cond_type_embedding = params.use_cond_type_embedding\n        self.vision_in_dim = params.vision_in_dim\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\n        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)\n        self.time_in = MLPEmbedder(in_dim=256, hidden_dim=self.hidden_size, 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, dtype=dtype, device=device, operations=operations) if params.guidance_embed else nn.Identity()","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy/ldm/hunyuan_video/model.py#L196-L232","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the checkpoint's original config mapping (all key names must match HunyuanVideoParams fields exactly)","Set num_heads to hidden_size // 128 (typical head_dim) or another exact divisor","Validate the kwargs dict before construction: hidden_size % num_heads == 0"],"exampleFix":"# before: typo leaves num_heads at default\nmodel = HunyuanVideoTransformer(num_head=24, hidden_size=3072)\n# after\nmodel = HunyuanVideoTransformer(num_heads=24, hidden_size=3072)","handlingStrategy":"validation","validationCode":"assert kwargs['hidden_size'] % kwargs['num_heads'] == 0","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Diff your kwargs dict against HunyuanVideoParams field names before construction","Unit-test config loading for each supported checkpoint"],"tags":["hunyuan-video","config","attention","init"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}