What causes "dimension index {dim} is too large for tensor rank {rank}" in huggingface/candle?

Print t.rank() (or len(t.shape)) and verify dim < rank

dimension index {dim} is too large for tensor rank {rank}

Error message

dimension index {dim} is too large for tensor rank {rank}

What it means

Thrown by candle-pyo3's `actual_dim` when a non-negative dimension index passed to operations like index_select, gather, squeeze, narrow, argmax_keepdim or argmin_keepdim is >= the tensor's rank. It validates that the dim refers to an existing axis before delegating to the candle core op.

Source

Thrown at candle-pyo3/src/lib.rs:191

        let index = index as usize;
        if dim <= index {
            ::candle::bail!("index {index} is too large for tensor dimension {dim}")
        }
        Ok(index)
    } else {
        if (dim as i64) < -index {
            ::candle::bail!("index {index} is too low for tensor dimension {dim}")
        }
        Ok((dim as i64 + index) as usize)
    }
}

fn actual_dim(t: &Tensor, dim: i64) -> ::candle::Result<usize> {
    let rank = t.rank();
    if 0 <= dim {
        let dim = dim as usize;
        if rank <= dim {
            ::candle::bail!("dimension index {dim} is too large for tensor rank {rank}")
        }
        Ok(dim)
    } else {
        if (rank as i64) < -dim {
            ::candle::bail!("dimension index {dim} is too low for tensor rank {rank}")
        }
        Ok((rank as i64 + dim) as usize)
    }
}

// TODO: Something similar to this should probably be a part of candle core.
trait MapDType {
    type Output;
    fn f<T: PyWithDType>(&self, t: &Tensor) -> PyResult<Self::Output>;

    fn map(&self, t: &Tensor) -> PyResult<Self::Output> {
        match t.dtype() {
            DType::U8 => self.f::<u8>(t),

View on GitHub (pinned to d5fee525bf)

Solutions

Print t.rank() (or len(t.shape)) and verify dim < rank
Use negative dims (-1 for the last axis), which actual_dim supports
Fix the hard-coded dim constant to match the actual tensor rank

Example fix

// before
t.squeeze(3)  # rank-3 tensor, valid dims 0..2
// after
assert 3 < t.rank()
t.squeeze(-1)  # operate on last axis regardless of rank

Defensive patterns

Strategy: validation

Validate before calling

let rank = t.rank();
if dim < 0 || dim as usize >= rank { panic!("dim {} invalid for rank {}", dim, rank); }

Type guard

fn is_valid_dim(rank: usize, dim: i64) -> bool {
    (-(rank as i64)..(rank as i64)).contains(&dim)
}

Try / catch

match t.squeeze(dim) {
    Ok(v) => v,
    Err(e) if e.to_string().contains("too large") => return Err(e),
    Err(e) => return Err(e),
}

Prevention

Derive dims from t.rank()/t.dims() instead of hard-coding
Use negative dims (-1) for axis-relative operations
Assert tensor rank after every reshape/squeeze in the pipeline

When it happens

Trigger: Calling any of the bound ops with dim = rank or higher, e.g. squeeze(3) on a rank-3 tensor, or narrow(4, ...) on a 4-D tensor (valid dims 0-3).

Common situations: Hard-coded dim values written for a different model architecture, forgetting batch/channel axes, or tensors that lost a dimension after a squeeze/reshape earlier in the pipeline.

Related errors

AI-assisted analysis of huggingface/candle@d5fee525bf (2026-09-02). Data as JSON: /api/errors/0e3208597dd0bb42. Report an issue: GitHub.