gguf: tensor_count {tensor_count} exceeds max {GGUF_MAX_ARRA

Error message

gguf: tensor_count {tensor_count} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}

What it means

candle guards against absurd header-declared tensor counts before allocating. The GGUF header contains a tensor_count field; a malicious or corrupt file can declare a huge count that would cause OOM or DoS during parsing. Values above GGUF_MAX_ARRAY_ELEMENTS are rejected outright.

Source

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

            Self::Array => 4 + magic.length_prefix_size(),
        }
    }
}

impl Content {
    pub fn read<R: std::io::Seek + std::io::Read>(reader: &mut R) -> Result<Self> {
        // Capture the file size once so the bounds checks below don't have to
        // seek to the end and back on every length-prefixed read.
        let start = reader.stream_position()?;
        let file_size = reader.seek(std::io::SeekFrom::End(0))?;
        reader.seek(std::io::SeekFrom::Start(start))?;

        let magic = VersionedMagic::read(reader)?;
        let tensor_count = read_length(reader, &magic)?;
        let metadata_kv_count = read_length(reader, &magic)?;

        if tensor_count > GGUF_MAX_ARRAY_ELEMENTS {
            crate::bail!("gguf: tensor_count {tensor_count} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}")
        }
        if metadata_kv_count > GGUF_MAX_ARRAY_ELEMENTS {
            crate::bail!(
                "gguf: metadata_kv_count {metadata_kv_count} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}"
            )
        }

        // Reject header-declared counts that can't fit in the file at minimum size.
        // Per-entry minima: a metadata kv is at least `key_len_prefix + u32 value_type
        // + 1 byte value`; a tensor info is at least `name_len_prefix + u32 n_dims
        // + u32 dtype + u64 offset`.
        let prefix = magic.length_prefix_size();
        let min_per_kv = prefix + 4 + 1;
        let min_per_tensor = prefix + 4 + 4 + 8;
        let needed = metadata_kv_count
            .saturating_mul(min_per_kv)
            .saturating_add(tensor_count.saturating_mul(min_per_tensor));
        let remaining = remaining_bytes(reader, file_size)?;

View on GitHub (pinned to d5fee525bf)

Solutions

Re-download or regenerate the GGUF file and verify its checksum
Confirm the file starts with the GGUF magic bytes before parsing
Check available disk space / download completeness

Example fix

// before
let file = File::open("model.gguf")?; // truncated download
let gguf = GgufFile::from_reader(&mut BufReader::new(file))?;
// after
// verify checksum before parsing
let bytes = std::fs::read("model.gguf")?;
assert_eq!(&bytes[..4], b"GGUF", "not a valid gguf file");
assert_eq!(sha256(&bytes), EXPECTED_SHA256);
let gguf = GgufFile::from_reader(&mut std::io::Cursor::new(bytes))?;

Defensive patterns

Strategy: validation

Validate before calling

let bytes = std::fs::read("model.gguf")?;
if &bytes[..4] != b"GGUF" { return Err(anyhow!("invalid magic")); }
// sanity check declared counts region by ensuring file size is plausible (> header)
if bytes.len() < 32 { return Err(anyhow!("file too small for gguf header")); }

Try / catch

match GgufFile::from_reader(&mut reader) {
    Ok(g) => g,
    Err(e) if e.to_string().contains("tensor_count") => {
        eprintln!("model.gguf appears corrupt; re-download it");
        return Err(e.into());
    }
    Err(e) => return Err(e.into()),
}

Prevention

Always verify checksums of downloaded GGUF models
Check download completeness (size comparison) before loading
Only load GGUF files from trusted sources

When it happens

Trigger: GgufFile::read on a file whose header tensor_count exceeds GGUF_MAX_ARRAY_ELEMENTS — i.e., a corrupted, truncated, or maliciously crafted GGUF file.

Common situations: Incomplete download of a quantized model; bit-rotted file on disk; adversarial model file; reading a non-GGUF binary as GGUF so random bytes are interpreted as counts.

Related errors

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