gguf: tensor '{tensor_name}' has {n_dimensions} dimensions,

Error message

gguf: tensor '{tensor_name}' has {n_dimensions} dimensions, max is {GGUF_MAX_TENSOR_DIMS}

What it means

Each tensor in a GGUF file declares its number of dimensions. candle enforces a sanity cap (GGUF_MAX_TENSOR_DIMS) to prevent absurd dimension vectors from exhausting memory. A declared dim count above the cap indicates a corrupt or malicious file.

Source

Thrown at candle-core/src/quantized/gguf_file.rs:519

            crate::bail!(
                "gguf: header declares {tensor_count} tensors and {metadata_kv_count} metadata entries, needs at least {needed} bytes, only {remaining} remaining"
            )
        }

        let mut metadata = HashMap::new();
        for _idx in 0..metadata_kv_count {
            let key = read_string(reader, &magic, file_size)?;
            let value_type = reader.read_u32::<LittleEndian>()?;
            let value_type = ValueType::from_u32(value_type)?;
            let value = Value::read(reader, value_type, &magic, 0, file_size)?;
            metadata.insert(key, value);
        }
        let mut tensor_infos = HashMap::new();
        for _idx in 0..tensor_count {
            let tensor_name = read_string(reader, &magic, file_size)?;
            let n_dimensions = reader.read_u32::<LittleEndian>()?;
            if n_dimensions > GGUF_MAX_TENSOR_DIMS {
                crate::bail!(
                    "gguf: tensor '{tensor_name}' has {n_dimensions} dimensions, max is {GGUF_MAX_TENSOR_DIMS}"
                )
            }

            let mut dimensions: Vec<usize> = match magic {
                VersionedMagic::GgufV1 => {
                    let mut dimensions = vec![0; n_dimensions as usize];
                    reader.read_u32_into::<LittleEndian>(&mut dimensions)?;
                    dimensions.into_iter().map(|c| c as usize).collect()
                }
                VersionedMagic::GgufV2 | VersionedMagic::GgufV3 => {
                    let mut dimensions = vec![0; n_dimensions as usize];
                    reader.read_u64_into::<LittleEndian>(&mut dimensions)?;
                    dimensions.into_iter().map(|c| c as usize).collect()
                }
            };

            dimensions.reverse();

View on GitHub (pinned to d5fee525bf)

Solutions

Re-convert the model with a current, reputable GGUF converter (llama.cpp convert script) and verify checksum
Re-download the file and verify integrity
Confirm the file was produced for the GGUF spec version candle supports

Defensive patterns

Strategy: validation

Validate before calling

// only load files converted with your verified pipeline
assert_eq!(&std::fs::read("model.gguf")?[..4], b"GGUF");
assert_eq!(sha256_file("model.gguf")?, EXPECTED_SHA256);

Try / catch

match GgufFile::from_reader(&mut reader) {
    Ok(g) => g,
    Err(e) if e.to_string().contains("dimensions, max is") => {
        eprintln!("corrupt or incompatible gguf tensor metadata; re-convert the model");
        return Err(e.into());
    }
    Err(e) => return Err(e.into()),
}

Prevention

Re-convert models with the current llama.cpp convert script
Verify checksums of converted files
Don't use gguf files from untrusted sources

When it happens

Trigger: GgufFile::read while parsing tensor infos: a tensor entry's n_dimensions u32 field exceeds GGUF_MAX_TENSOR_DIMS.

Common situations: Reading a GGUF file produced by an incompatible or buggy converter; corrupted downloads; files from untrusted sources.

Related errors

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