{"record":{"id":"c08e40b1c0467c91","repo":"invoke-ai/InvokeAI","slug":"input-img-and-txt-tensors-must-have-3-dimensions-c08e40","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":"invokeai/backend/flux/model.py","lineNumber":107,"sourceCode":"\n    def forward(\n        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        timestep_index: int,\n        total_num_timesteps: int,\n        controlnet_double_block_residuals: list[Tensor] | None,\n        controlnet_single_block_residuals: list[Tensor] | None,\n        ip_adapter_extensions: list[XLabsIPAdapterExtension],\n        regional_prompting_extension: RegionalPromptingExtension,\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        # running on sequences img\n        img = self.img_in(img)\n        vec = self.time_in(timestep_embedding(timesteps, 256))\n        if self.params.guidance_embed:\n            if guidance is None:\n                raise ValueError(\"Didn't get guidance strength for guidance distilled model.\")\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        ids = torch.cat((txt_ids, img_ids), dim=1)\n        pe = self.pe_embedder(ids)\n\n        # Validate double_block_residuals shape.\n        if controlnet_double_block_residuals is not None:\n            assert len(controlnet_double_block_residuals) == len(self.double_blocks)\n        for block_index, block in enumerate(self.double_blocks):","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/flux/model.py#L89-L125","documentation":"Flux.forward expects the image latent tensor (img) and text embedding tensor (txt) to be rank-3: (batch, seq_len, channels). If either has another rank (e.g. 4D image latents straight from the VAE, or 2D unbatched tensors), the sequence-linear projections downstream would be wrong, so forward raises immediately.","triggerScenarios":"Calling model.forward (or __call__) with img or txt shaped (B,C,H,W) instead of (B,seq,C); passing a text encoder output without flattening token dims; passing an unbatched (seq,C) tensor.","commonSituations":"Wiring a diffusers-style UNet pipeline to Flux directly; forgetting pack/unpack of latents (Flux works on packed 2x2 patch latents of shape B, seq, 64); custom pipelines passing VAE latents untransformed.","solutions":["Reshape img to (batch, seq_len, channels) — for Flux, pack latents first (2x2 patchify then rearrange to B, seq, C)","Reshape txt to (batch, seq_len, embed_dim) from your text encoder output","Add .unsqueeze(0) if you forgot the batch dimension"],"exampleFix":"// before\nimg = vae.encode(image)  # B,C,H,W\nmodel(img=img, txt=t5_embeddings, ...)\n// after\nimg = pack_latents(vae.encode(image))  # B, seq, 64\nmodel(img=img, txt=t5_embeddings, ...)  # txt: B, seq, 4096","handlingStrategy":"validation","validationCode":"assert img.ndim == 3 and txt.ndim == 3, f\"img: {img.shape}, txt: {txt.shape} — both must be (batch, seq, channels)\"","typeGuard":"def is_rank3_tensor(t: torch.Tensor) -> bool:\n    return isinstance(t, torch.Tensor) and t.ndim == 3","tryCatchPattern":"try:\n    output = model(img=img, txt=txt, ...)\nexcept ValueError as e:\n    if \"must have 3 dimensions\" in str(e):\n        img = img.flatten(2).transpose(1, 2) if img.ndim == 4 else img.unsqueeze(0)\n        txt = txt.unsqueeze(0) if txt.ndim == 2 else txt\n        output = model(img=img, txt=txt, ...)\n    else:\n        raise","preventionTips":["Pack VAE latents (2x2 patchify) before passing as img","Squeeze token dims of text encoder output to (B, seq, C)","Log tensor shapes at pipeline boundaries when debugging"],"tags":["flux","tensor-shape","runtime-validation","forward-pass"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}