{"record":{"id":"a363cacb5df2eb15","repo":"hpcaitech/Open-Sora","slug":"input-img-and-txt-tensors-must-have-3-dimensions","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":"opensora/models/mmdit/model.py","lineNumber":173,"sourceCode":"        self,\n        img: Tensor,\n        img_ids: Tensor,\n        txt: Tensor,  # t5 encoded vec\n        txt_ids: Tensor,\n        timesteps: Tensor,\n        y_vec: Tensor,  # clip encoded vec\n        cond: Tensor = None,\n        guidance: Tensor | None = None,\n    ):\n        \"\"\"\n        obtain the processed:\n            img: projected noisy img latent,\n            txt: text context (from t5),\n            vec: clip encoded vector,\n            pe: the positional embeddings for concatenated img and txt\n        \"\"\"\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        if self.config.cond_embed:\n            if cond is None:\n                raise ValueError(\"Didn't get conditional input for conditional model.\")\n            img = img + self.cond_in(cond)\n\n        vec = self.time_in(timestep_embedding(timesteps, 256))\n        if self.config.guidance_embed:\n            if guidance is None:\n                raise ValueError(\n                    \"Didn't get guidance strength for guidance distilled model.\"\n                )\n            vec = vec + self.guidance_in(timestep_embedding(guidance, 256))\n        vec = vec + self.vector_in(y_vec)\n\n        txt = self.txt_in(txt)","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/hpcaitech/Open-Sora/blob/7ad6a96a135feb81f755c84fb391818718f6beb2/opensora/models/mmdit/model.py#L155-L191","documentation":"prepare_block_inputs expects img (noisy latent sequence) and txt (T5 text embeddings) as rank-3 [B, L, C] tensors — MMDiT operates on token sequences. If either tensor is 4D (e.g. raw [B, C, T, H, W] latents not patchified) or 2D (unbatched), it raises.","triggerScenarios":"Calling the model forward with img that still has spatial dims (missing patchify/flatten step) or txt embeddings with a squeezed/missing batch dimension; also affects forward_ckpt and forward_selective_ckpt paths.","commonSituations":"Custom pipelines that pass VAE latents straight to MMDit without the patchifier; accidentally squeezing text embeddings; batch-of-one code that drops the batch dim.","solutions":["Patchify/flatten img to [B, seq_len, channels] (use the model's patch embed / arrange '(b t h w) (c p1 p2 p3)')","Ensure txt has shape [B, L_txt, txt_channels]; re-insert the batch dim with .unsqueeze(0) if needed","Print img.shape and txt.shape right before the call and confirm both are 3-D"],"exampleFix":"# before\nout = model(img=latents_bcthw, txt=t5_emb)  # img.ndim == 4 → error\n# after\nimg = patchify(latents_bcthw)  # → [B, L, C]\ntxt = t5_emb if t5_emb.ndim == 3 else t5_emb.unsqueeze(0)\nout = model(img=img, txt=txt, ...)","handlingStrategy":"type-guard","validationCode":"assert img.ndim == 3 and txt.ndim == 3, f\"img {tuple(img.shape)} txt {tuple(txt.shape)} must be [B, L, C]\"","typeGuard":"def is_seq3(t: torch.Tensor) -> bool:\n    return torch.is_tensor(t) and t.dim() == 3","tryCatchPattern":null,"preventionTips":["Always patchify latents before the MMDiT forward","Guard batch-of-one code against squeezed batch dims","Log shapes at pipeline stage boundaries"],"tags":["transformer","mmdit","tensor-shape","pipeline"],"backgroundTag":"wrong-tensor-rank","analyzedSha":"7ad6a96a135feb81f755c84fb391818718f6beb2","analyzedAt":"2026-08-28T16:58:37.171Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}