{"record":{"id":"bd3b6f2025b51e13","repo":"huggingface/candle","slug":"unexpected-shape-for-img-bd3b6f","errorCode":null,"errorMessage":"unexpected shape for img {:?}","messagePattern":"unexpected shape for img (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"candle-transformers/src/models/flux/quantized_model.rs","lineNumber":435,"sourceCode":"}\n\nimpl super::WithForward for Flux {\n    #[allow(clippy::too_many_arguments)]\n    fn 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: Option<&Tensor>,\n    ) -> Result<Tensor> {\n        if txt.rank() != 3 {\n            candle::bail!(\"unexpected shape for txt {:?}\", txt.shape())\n        }\n        if img.rank() != 3 {\n            candle::bail!(\"unexpected shape for img {:?}\", img.shape())\n        }\n        let dtype = img.dtype();\n        let pe = {\n            let ids = Tensor::cat(&[txt_ids, img_ids], 1)?;\n            ids.apply(&self.pe_embedder)?\n        };\n        let mut txt = txt.apply(&self.txt_in)?;\n        let mut img = img.apply(&self.img_in)?;\n        let vec_ = timestep_embedding(timesteps, 256, dtype)?.apply(&self.time_in)?;\n        let vec_ = match (self.guidance_in.as_ref(), guidance) {\n            (Some(g_in), Some(guidance)) => {\n                (vec_ + timestep_embedding(guidance, 256, dtype)?.apply(g_in))?\n            }\n            _ => vec_,\n        };\n        let vec_ = (vec_ + y.apply(&self.vector_in))?;\n\n        // Double blocks","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/huggingface/candle/blob/d5fee525bfde3273eb7c9b75fd2bc4937be867ca/candle-transformers/src/models/flux/quantized_model.rs#L417-L453","documentation":"Same rank check as for txt but for img: FluxModel forward requires img (image token embeddings / latents) to be rank-3 [batch, img_seq, hidden]. A rank != 3 image tensor cannot be position-embedded and attention-processed, so forward bails.","triggerScenarios":"Passing latents as [b, c, h, w] (4D conv-style) without flattening to a token sequence, or a 2D [img_seq, hidden] tensor missing the batch dimension.","commonSituations":"Reusing latent tensors directly from a diffusion pipeline that keeps conv layout; forgetting to pack image patches into a sequence; manual inference scripts that skip Flux's latent packing step.","solutions":["Reshape latents to [batch, img_seq, hidden] — pack 2x2 patches via rearrange before calling forward","Unsqueeze(0) if the batch dim is missing","Confirm img.dims().len() == 3 prior to the call"],"exampleFix":"// before\nlet img = img; // [b, 16, h, w]\nmodel.forward(&txt, &img, ...)?;\n// after\nlet (b, _c, h, w) = img.dims4()?;\nlet img = img.reshape((b, 16, h / 2, 2, w / 2, 2))?\n    .permute((0, 2, 4, 1, 3, 5))?\n    .reshape((b, (h / 2) * (w / 2), 16 * 4))?;\nmodel.forward(&txt, &img, ...)?;","handlingStrategy":"validation","validationCode":"assert_eq!(img.dims().len(), 3, \"img must be [batch, img_seq, hidden], got {:?}\", img.shape());","typeGuard":"fn is_rank3(t: &candle_core::Tensor) -> bool { t.rank() == 3 }","tryCatchPattern":"match model.forward(&txt, &img, /* ... */) {\n    Err(e) if e.to_string().contains(\"unexpected shape for img\") =>\n        Err(anyhow!(\"pack latents to token sequence [b, seq, d] before forward: {e}\")),\n    r => r.map_err(Into::into),\n}","preventionTips":["Pack conv-layout latents (b,c,h,w) into patch tokens before forward","Keep batch dimension on image tensors even for single-image inference","Reuse the flux example's prepare_latents/packing utilities"],"tags":["tensor-shape","flux","latents"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"d5fee525bfde3273eb7c9b75fd2bc4937be867ca","analyzedAt":"2026-09-02T00:15:47.023Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}