ErrLookup › Background articles › Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect

Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect

Tensor shape mismatch errors fire when a tensor's dimensions don't match a contract another component depends on — a kernel's expected strides, a layer's assumed model width, or metadata describing a batch. You meet them as ValueErrors naming expected and received shapes, raised by validation guards in attention kernels, multimodal preprocessors, quantization checkpoint checkers, CRF layers, and functional model call sites across libraries like SGLang, Keras, HanLP, and ruflo. They almost always mean two producers in the pipeline sized the same data differently, not that the math itself failed.

Distilled from 203 documented records across 6 repositories.

Background

Shape-mismatch errors come from validation guards sitting at the boundary between a producer and a consumer of a tensor. Kernels and low-level ops (SGLang's Triton decode kernels, fused RoPE pooling, FlashAttention in ruflo) check incoming tensors against an exact layout — e.g. d_cache must be [slots, HV, L, V] because the kernel indexes with those strides — and refuse anything else rather than silently corrupt memory. Higher-level layers (Keras GroupedQueryAttention, TimeDistributed, Functional ops; HanLP's TorchCRF) validate during shape inference or at call time, comparing symbolic input shapes against traced shapes or against each other. A third variant checks tensor-against-metadata consistency: SGLang's multimodal paths compare vision-encoder token counts against preprocessor grid metadata, and its quantization checkers verify checkpoint scale tensors against packed weight shapes.

From the caller's side the error usually prints both sides of the disagreement — "expected shape {X}, got {Y}" or "got {a} keys, {b} values" — which is the primary diagnostic: the diff between the two shapes tells you which dimension drifted. The rank (number of axes) is the most common offender (a 2-D tensor where 3-D is required, or a traced 3-D input receiving 4-D data), followed by a specific dimension disagreeing (head counts, per-token row counts, feature widths).

The family varies by library in what the shapes are measured against. In SGLang the reference is often derived from another tensor or config (num_v_heads from the model config, token counts from preprocessor metadata, HV/K inferred from initial_state), so a mismatch usually means config, checkpoint, and runtime allocation drifted apart. In Keras the reference is the shape the graph was traced or built with, so mismatches surface after data pipelines add or drop a batch axis. In HanLP it is pairwise consistency between two tensors (emissions vs tags) that must travel together; in ruflo it is parallel arrays (keys/values, query/key dimensions) that must be built from the same source. Note also that some checks are stricter than sister APIs — ruflo requires d_v == d_k where PyTorch-style attention allows them to differ — so ported code can trip checks that never fired in the original framework.

Common causes

What usually fixes it

Documented occurrences

…and 183 more across the corpus — use search.

Honest provenance: generated on 2026-08-28 from AI-assisted analysis of the linked records. See how records are made.