{"record":{"id":"1642b759c96e2c04","repo":"Comfy-Org/ComfyUI","slug":"input-img-and-txt-tensors-must-have-3-dimensions-1642b7","errorCode":null,"errorMessage":"Input img and txt tensors must have 3 dimensions.","messagePattern":"Input img and txt tensors must have 3 dimensions\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy/ldm/flux/controlnet.py","lineNumber":122,"sourceCode":"                    operations.Conv2d(16, 16, 3, padding=1, stride=2, dtype=dtype, device=device),\n                    nn.SiLU(),\n                    operations.Conv2d(16, 16, 3, padding=1, dtype=dtype, device=device)\n                )\n\n    def forward_orig(\n        self,\n        img: Tensor,\n        img_ids: Tensor,\n        controlnet_cond: Tensor,\n        txt: Tensor,\n        txt_ids: Tensor,\n        timesteps: Tensor,\n        y: Tensor,\n        guidance: Tensor = None,\n        control_type: Tensor = None,\n    ) -> Tensor:\n        if img.ndim != 3 or txt.ndim != 3:\n            raise ValueError(\"Input img and txt tensors must have 3 dimensions.\")\n\n        if y is None:\n            y = torch.zeros((img.shape[0], self.params.vec_in_dim), device=img.device, dtype=img.dtype)\n        else:\n            y = y[:, :self.params.vec_in_dim]\n\n        # running on sequences img\n        img = self.img_in(img)\n\n        controlnet_cond = self.pos_embed_input(controlnet_cond)\n        img = img + controlnet_cond\n        vec = self.time_in(timestep_embedding(timesteps, 256))\n        if self.params.guidance_embed:\n            vec = vec + self.guidance_in(timestep_embedding(guidance, 256))\n        vec = vec + self.vector_in(y)\n        txt = self.txt_in(txt)\n\n        if self.controlnet_mode_embedder is not None and len(control_type) > 0:","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy/ldm/flux/controlnet.py#L104-L140","documentation":"Flux ControlNet's __call__ requires img (latent image tokens) and txt (text tokens) to be rank-3 tensors of shape (batch, sequence, channel). Anything else raises ValueError immediately. This contract matches the packed-token format produced by Flux latents and T5 text encodings before entering the controlnet.","triggerScenarios":"Passing a 4D image tensor (B,C,H,W) that was not patchified/packed into (B,seq,dim); passing text embeddings with an extra batch dim; reusing a controlnet wrapper with tensors formatted for a different conditioning path.","commonSituations":"Custom nodes calling the Flux controlnet forward directly with VAE latents instead of Flux sequence latents; importing code from a diffusers-style pipeline where tensor layouts differ; empty or scalar edge-case tensors.","solutions":["Feed the same packed (B, seq, dim) img/txt tensors that the main Flux model consumes (from Flux latent conditioning, not raw VAE latents).","If your tensor is (B,C,H,W), apply the Flux patchify step first to reach rank 3.","Use the stock Flux controlnet ComfyUI nodes, which build correctly shaped inputs, instead of calling the module directly."],"exampleFix":"# before (raw VAE latent, rank 4)\nctrl = controlnet(img_latent_bchw, img_ids, cond, txt_btd, txt_ids, t, y)\n\n# after (packed sequence, rank 3)\nimg_seq = pack_latents(img_latent_bchw)  # -> (B, H/2*W/2, C*4)\nctrl = controlnet(img_seq, img_ids, cond, txt_btd, txt_ids, t, y)","handlingStrategy":"validation","validationCode":"assert img.ndim == 3 and txt.ndim == 3, f\"img/txt must be (B,seq,dim); got img {tuple(img.shape)}, txt {tuple(txt.shape)}\"","typeGuard":"def is_flux_sequence(t: \"torch.Tensor\") -> bool:\n    return t.ndim == 3","tryCatchPattern":null,"preventionTips":["Always pass the packed sequence latents produced by the Flux conditioning path, never raw VAE latents.","Prefer stock Flux controlnet nodes over direct module calls.","Unsqueeze single samples to restore the batch dim."],"tags":["flux","controlnet","tensor-shape","input-validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}