{"record":{"id":"a158751312533430","repo":"Comfy-Org/ComfyUI","slug":"input-img-and-txt-tensors-must-have-3-dimensions-a15875","errorCode":null,"errorMessage":"Input img and txt tensors must have 3 dimensions.","messagePattern":"Input img and txt tensors must have 3 dimensions\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy/ldm/flux/model.py","lineNumber":166,"sourceCode":"        self,\n        img: Tensor,\n        img_ids: Tensor,\n        txt: Tensor,\n        txt_ids: Tensor,\n        timesteps: Tensor,\n        y: Tensor,\n        guidance: Tensor = None,\n        control = None,\n        timestep_zero_index=None,\n        transformer_options={},\n        attn_mask: Tensor = None,\n    ) -> Tensor:\n\n        transformer_options = transformer_options.copy()\n        patches = transformer_options.get(\"patches\", {})\n        patches_replace = transformer_options.get(\"patches_replace\", {})\n        if img.ndim != 3 or txt.ndim != 3:\n            raise ValueError(\"Input img and txt tensors must have 3 dimensions.\")\n\n        # running on sequences img\n        img = self.img_in(img)\n        vec = self.time_in(timestep_embedding(timesteps, 256).to(img.dtype))\n        if self.params.guidance_embed:\n            if guidance is not None:\n                vec = vec + self.guidance_in(timestep_embedding(guidance, 256).to(img.dtype))\n\n        if self.vector_in is not None:\n            if y is None:\n                y = torch.zeros((img.shape[0], self.params.vec_in_dim), device=img.device, dtype=img.dtype)\n            vec = vec + self.vector_in(y[:, :self.params.vec_in_dim])\n\n        if self.txt_norm is not None:\n            txt = self.txt_norm(txt)\n        txt = self.txt_in(txt)\n\n        if \"post_input\" in patches:","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy/ldm/flux/model.py#L148-L184","documentation":"The main Flux forward() enforces the same token-sequence contract as the controlnet: img and txt must be rank-3 (batch, sequence, channel) tensors. Raw 4D image latents, unbatched 2D tensors, or mis-shaped conditioning raise ValueError before any compute. This mirrors the packed-token format Flux uses end to end.","triggerScenarios":"Calling model.forward() (or a sampler invoking it) with img of shape (B,C,H,W) instead of packed (B,seq,dim); txt embeddings of rank 2 (missing batch dim); tensors flattened incorrectly by a custom patch or wrapper.","commonSituations":"Custom sampling loops that bypass ComfyUI's model patcher and pass VAE latents directly; transformer patches (patches_replace) that reshape x and return the wrong rank; debugging code that feeds a single image without a batch dim.","solutions":["Pass Flux sequence latents (B, seq, dim) — in ComfyUI flows these come from the Flux model's own latent packing, not from a VAE decode/encode round trip.","If writing a custom patch that touches x, return tensors with the same rank you received.","Add a batch dimension to single samples: txt = txt.unsqueeze(0), img = img.unsqueeze(0)."],"exampleFix":"# before\nnoise_pred = model(x_bchw, t, context=txt_2d)\n\n# after\nx_seq = pack(x_bchw)          # (B, seq, dim)\ntxt = txt_2d.unsqueeze(0)     # (1, seq, dim)\nnoise_pred = model(x_seq, t, context=txt)","handlingStrategy":"validation","validationCode":"assert img.ndim == 3 and txt.ndim == 3, f\"Flux forward needs (B,seq,dim); img ndim={img.ndim}, txt ndim={txt.ndim}\"","typeGuard":"def is_flux_sequence(t: \"torch.Tensor\") -> bool:\n    return t.ndim == 3","tryCatchPattern":null,"preventionTips":["Route calls through ComfyUI's model patcher/sampler so latent packing is handled for you.","In custom transformer patches, preserve tensor rank on return.","unsqueeze(0) single-image batches before forward."],"tags":["flux","tensor-shape","input-validation","forward"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}