What causes "Dimensions differ and cannot be broadcasted." in tracel-ai/burn?

Ensure batch dimensions match, or make one side 1 to enable broadcasting (e.g. reshape to [1,3,4]).

Dimensions differ and cannot be broadcasted.

Error message

Dimensions differ and cannot be broadcasted.

What it means

output_shape supports batched/broadcast matmul, but a leading (batch) dimension pair can only differ if one of them is 1 (broadcastable). If both dimensions are non-1 and unequal, broadcasting is impossible and the backend panics.

Source

Thrown at crates/burn-ndarray/src/ops/matmul.rs:166

        // Compatible dimensions are:
        //   1. Both dimensions are equal.
        //   2. One of the dimensions is equal to 1.
        let o_dim: usize;
        if l_dim == r_dim {
            o_dim = l_dim; // both dimensions are equal
            l_strides.push(cur_l_stride);
            r_strides.push(cur_r_stride);
        } else if l_dim == 1 {
            o_dim = r_dim; // broadcast the left
            l_strides.push(0);
            r_strides.push(cur_r_stride);
        } else if r_dim == 1 {
            o_dim = l_dim; // broadcast the right
            l_strides.push(cur_l_stride);
            r_strides.push(0);
        } else {
            panic!("Dimensions differ and cannot be broadcasted.");
        }
        osh[i] = o_dim;
        o_strides.push(cur_o_stride);
        cur_o_stride *= o_dim;

        cur_l_stride *= l_dim;
        cur_r_stride *= r_dim;
    }
    l_strides.reverse();
    r_strides.reverse();
    o_strides.reverse();

    (
        Shape::from(osh),
        Strides::new(l_strides),
        Strides::new(r_strides),
        Strides::new(o_strides),
    )

View on GitHub (pinned to d16f7ba2ed)

Solutions

Ensure batch dimensions match, or make one side 1 to enable broadcasting (e.g. reshape to [1,3,4]).
Use expand/repeat on the smaller tensor to match the larger batch shape explicitly.
Align data pipeline batch sizes before matmul.
Check that the tensors come from compatible batched sources (same batch dim).

Example fix

// before: [2,3,4] x [5,4,6]
let y = a.matmul(b); // panic
// after
let b2 = b.reshape([1, 5, 4, 6]); // or fix a's batch dim to 5
let y = a.reshape([1, 2, 3, 4]).matmul(b2); // dims of size 1 broadcast

Defensive patterns

Strategy: validation

Validate before calling

fn ensure_broadcastable_batch_dims(lsh: &[usize], rsh: &[usize]) {
    for (l, r) in lsh[..lsh.len()-2].iter().zip(&rsh[..rsh.len()-2]) {
        assert!(l == r || *l == 1 || *r == 1, "batch dims {l} vs {r} not broadcastable");
    }
}

Prevention

Fix batch sizes across the whole training/eval pipeline.
Use size-1 leading dims when you intend broadcasting.
Expand explicitly instead of relying on implicit broadcast in complex graphs.
Assert batch dims equal at merge points of multi-branch models.

When it happens

Trigger: matmul of tensors with batch shapes like [2,3,4] x [5,4,6] where dim0 is 2 vs 5 (neither is 1); calling matmul with mismatched batch or channel counts.

Common situations: Batch-size mismatch between two pipeline branches; mixing per-sample and batched tensors; concatenating datasets with different batch sizes.

Related errors

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/d173c367321cd4a4. Report an issue: GitHub.