{"record":{"id":"3d24e16a53bb1394","repo":"huggingface/candle","slug":"unexpected-shape-for-txt","errorCode":null,"errorMessage":"unexpected shape for txt {:?}","messagePattern":"unexpected shape for txt (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"candle-transformers/src/models/flux/model.rs","lineNumber":593,"sourceCode":"            final_layer,\n        })\n    }\n}\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        };","sourceCodeStart":575,"sourceCodeEnd":611,"githubUrl":"https://github.com/huggingface/candle/blob/d5fee525bfde3273eb7c9b75fd2bc4937be867ca/candle-transformers/src/models/flux/model.rs#L575-L611","documentation":"Flux::forward validates that the text-token tensor `txt` has rank 3 (batch, seq_len, hidden) before embedding and running the transformer. This bail fires when txt has any other rank, e.g. a 2D (seq_len, hidden) tensor with no batch dimension or unpooled embeddings passed without reshaping. It is an early input-shape sanity check before position embedding and attention are computed.","triggerScenarios":"Calling Flux forward (via generate or WithForward) passing txt built from T5 token embeddings without a batch dimension, e.g. shape (seq, 4096) instead of (1, seq, 4096); passing pooled CLIP embeddings or squeezed tensors as txt; batching errors that flatten the tensor.","commonSituations":"Writing custom sampling code around candle's Flux instead of using the included generate function and forgetting .unsqueeze(0); porting code from diffusers where tensor shapes are handled internally; concatenating batches incorrectly so the tensor gets flattened.","solutions":["Reshape txt to rank 3: (batch, seq_len, 4096) for Flux T5 embeddings — use `.unsqueeze(0)` if the batch dim is missing.","Check dtype/device-preserving reshape: `let txt = txt.reshape((b, seq, hidden))?;`","Ensure the tokenizer/pipeline produces per-batch embeddings; compare with candle's flux example (examples/flux-main.rs) txt preparation.","Log txt.shape() before calling forward to confirm rank and dims."],"exampleFix":"// before\nlet txt = t5_embeddings; // rank 2: (seq_len, 4096)\nmodel.forward(&img, &img_ids, &txt, &txt_ids, &t, &y, None)?;\n\n// after\nlet txt = t5_embeddings.unsqueeze(0)?; // rank 3: (1, seq_len, 4096)\nmodel.forward(&img, &img_ids, &txt, &txt_ids, &t, &y, None)?;","handlingStrategy":"validation","validationCode":"// Rust: guard before calling Flux::forward\nif txt.rank() != 3 {\n    return Err(candle_core::Error::Msg(format!(\n        \"txt must be (batch, seq, hidden); got shape {:?}\", txt.shape()\n    )));\n}","typeGuard":"fn is_rank3(t: &candle_core::Tensor) -> bool { t.rank() == 3 }","tryCatchPattern":"match flux.forward(&img, &img_ids, &txt, &txt_ids, &ts, &y, guidance) {\n    Ok(t) => t,\n    Err(e) if e.to_string().contains(\"unexpected shape for txt\") => {\n        let txt = txt.unsqueeze(0)?; // recover by adding batch dim once\n        flux.forward(&img, &img_ids, &txt, &txt_ids, &ts, &y, guidance)?\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Keep text embeddings batched end-to-end; do not squeeze the batch dimension after T5 encoding.","Use candle's flux example pipeline (examples/flux-main.rs) as the reference for tensor prep.","Print shapes of all five input tensors before forward during development.","Wrap shape-sensitive calls in helpers that assert rank/dims and fail with actionable messages."],"tags":["candle","tensor-shape","rank","flux","input-validation"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"d5fee525bfde3273eb7c9b75fd2bc4937be867ca","analyzedAt":"2026-09-02T00:15:47.023Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}