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

Verify tensor rank and ensure -rank <= dim < rank before the call

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

Error message

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

What it means

Thrown by candle-pyo3's `actual_dim` when a negative dimension index is more negative than -rank, so it cannot be resolved to a valid axis. This protects index_select, gather, squeeze, narrow, argmax_keepdim and argmin_keepdim from invalid axis references.

Source

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

    } 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),
            DType::U32 => self.f::<u32>(t),
            DType::I64 => self.f::<i64>(t),
            DType::BF16 => self.f::<bf16>(t),
            DType::F16 => self.f::<f16>(t),
            DType::F32 => self.f::<f32>(t),

View on GitHub (pinned to d5fee525bf)

Solutions

Verify tensor rank and ensure -rank <= dim < rank before the call
Use positive dim indices derived from t.rank() instead of negative ones
Check earlier ops (squeeze/reshape) that may have reduced rank unexpectedly

Example fix

// before
t.argmax_keepdim(-4)  # rank-3 tensor
// after
assert -t.rank() <= -4 < t.rank()  # fails here; use a valid dim
t.argmax_keepdim(-1)

Defensive patterns

Strategy: validation

Validate before calling

let rank = t.rank() as i64;
if !(-rank..rank).contains(&dim) { panic!("dim {} invalid for rank {}", dim, rank); }

Type guard

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

Try / catch

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

Prevention

Compute the last axis as rank-1 explicitly instead of -1 when rank is uncertain
Check rank after ops that may drop dimensions
Centralize dim selection in a helper that validates against rank

When it happens

Trigger: Passing dim = -(rank+1) or lower, e.g. dim=-4 on a rank-3 tensor, or dim=-1 on a scalar/0-rank tensor.

Common situations: Using -1 for the last axis on tensors that unexpectedly have fewer dimensions (e.g. after an accidental squeeze), or reusing dim constants across tensors of differing rank.

Related errors

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