{"record":{"id":"e32d69a9b57fd56e","repo":"huggingface/candle","slug":"the-number-of-encoder-hidden-states-is-not-equa","errorCode":null,"errorMessage":"The number of encoder hidden states {} is not equal to the number of linear layers {}","messagePattern":"The number of encoder hidden states (.+?) is not equal to the number of linear layers (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"candle-transformers/src/models/segformer.rs","lineNumber":558,"sourceCode":"        )?;\n        let classifier = conv2d_no_bias(\n            config.decoder_hidden_size,\n            num_labels,\n            1,\n            Conv2dConfig::default(),\n            vb.pp(\"classifier\"),\n        )?;\n        Ok(Self {\n            linear_c,\n            linear_fuse,\n            batch_norm,\n            classifier,\n        })\n    }\n\n    fn forward(&self, encoder_hidden_states: &[Tensor]) -> Result<Tensor> {\n        if encoder_hidden_states.len() != self.linear_c.len() {\n            candle::bail!(\n                \"The number of encoder hidden states {} is not equal to the number of linear layers {}\",\n                encoder_hidden_states.len(),\n                self.linear_c.len()\n            )\n        }\n        // most fine layer\n        let (_, _, upsample_height, upsample_width) = encoder_hidden_states[0].shape().dims4()?;\n        let mut hidden_states = Vec::with_capacity(self.linear_c.len());\n        for (hidden_state, mlp) in encoder_hidden_states.iter().zip(&self.linear_c) {\n            let (batch, _, height, width) = hidden_state.shape().dims4()?;\n            let hidden_state = mlp.forward(&hidden_state.flatten_from(2)?.permute((0, 2, 1))?)?;\n            let hidden_state = hidden_state.permute((0, 2, 1))?.reshape((\n                batch,\n                hidden_state.dim(2)?,\n                height,\n                width,\n            ))?;\n            let hidden_state = hidden_state.upsample_nearest2d(upsample_height, upsample_width)?;","sourceCodeStart":540,"sourceCodeEnd":576,"githubUrl":"https://github.com/huggingface/candle/blob/d5fee525bfde3273eb7c9b75fd2bc4937be867ca/candle-transformers/src/models/segformer.rs#L540-L576","documentation":"SegFormer's decode head applies one MLP linear layer per encoder stage. This error means the slice of encoder hidden states passed to `SegmentDecoderHead::forward` has a different length than the `linear_c` layer list built from `config.num_encoder_blocks` (4 stages by default). The library bails early rather than silently mis-zipping states to MLPs.","triggerScenarios":"Calling `forward` (or higher-level segmentation forward) with a Vec of hidden states whose count differs from the number of encoder blocks — e.g. passing only the last stage's output, passing 3 states from a modified encoder, or hand-constructing a config with a `num_encoder_blocks` value that doesn't match the checkpoint's actual stage count.","commonSituations":"Users feed the decoder only the final encoder output instead of all 4 multi-scale feature maps; or they truncate/extend hidden states for memory savings; or a fine-tuned/modified SegFormer variant changes the number of stages while reusing this head.","solutions":["Pass ALL per-stage hidden states from the encoder in order (fine-to-coarse), one per `num_encoder_blocks`.","Check the model config's `num_encoder_blocks` (default 4) and ensure the encoder actually returns that many feature maps.","If you only have one/few feature maps, build the head with a config whose `num_encoder_blocks` matches, or wrap states so the count matches.","Verify with candle_core::Error::backtrace / log the two counts in the message to see which side is wrong."],"exampleFix":"// before: only last stage\nlet features = vec![encoder.last_hidden_state];\nlet seg = head.forward(&features)?;\n// after: all stages\nlet features = encoder.all_hidden_states; // Vec<Tensor> of len num_encoder_blocks\nlet seg = head.forward(&features)?;","handlingStrategy":"validation","validationCode":"if states.len() != head.num_linear_layers() {\n    return Err(format!(\"expected {} hidden states, got {}\", head.num_linear_layers(), states.len()));\n}","typeGuard":"fn states_match_head(states: &[Tensor], head: &SegmentDecoderHead) -> bool {\n    states.len() == head.linear_c.len()\n}","tryCatchPattern":"let seg = match head.forward(&states) {\n    Ok(t) => t,\n    Err(e) if e.to_string().contains(\"not equal to the number of linear layers\") => {\n        candle::bail!(\"pass all {} encoder hidden states\", states_hint); \n    }\n    Err(e) => return Err(e.into()),\n};","preventionTips":["Always feed the full multi-scale feature list (one per encoder stage, default 4) from the encoder.","Log states.len() alongside config.num_encoder_blocks at startup.","Never truncate hidden states for memory without rebuilding the head config.","Keep num_encoder_blocks in sync with the checkpoint architecture when loading custom weights."],"tags":["tensor-shape","model-config","candle"],"backgroundTag":"tensor-count-mismatch","analyzedSha":"d5fee525bfde3273eb7c9b75fd2bc4937be867ca","analyzedAt":"2026-09-02T00:15:47.023Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}