gguf: array length {len} exceeds max {GGUF_MAX_ARRAY_ELEMENT

Error message

gguf: array length {len} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}

What it means

Value::read caps GGUF arrays at GGUF_MAX_ARRAY_ELEMENTS and throws this when the declared array length exceeds the cap. The length is read from the file header, so a huge declared length would otherwise cause enormous pre-allocation or DoS. This is a hardening guard against malformed or malicious files.

Source

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

            ValueType::I16 => Self::I16(reader.read_i16::<LittleEndian>()?),
            ValueType::U32 => Self::U32(reader.read_u32::<LittleEndian>()?),
            ValueType::I32 => Self::I32(reader.read_i32::<LittleEndian>()?),
            ValueType::U64 => Self::U64(reader.read_u64::<LittleEndian>()?),
            ValueType::I64 => Self::I64(reader.read_i64::<LittleEndian>()?),
            ValueType::F32 => Self::F32(reader.read_f32::<LittleEndian>()?),
            ValueType::F64 => Self::F64(reader.read_f64::<LittleEndian>()?),
            ValueType::Bool => match reader.read_u8()? {
                0 => Self::Bool(false),
                1 => Self::Bool(true),
                b => crate::bail!("unexpected bool value {b}"),
            },
            ValueType::String => Self::String(read_string(reader, magic, file_size)?),
            ValueType::Array => {
                let value_type = reader.read_u32::<LittleEndian>()?;
                let value_type = ValueType::from_u32(value_type)?;
                let len = read_length(reader, magic)?;
                if len > GGUF_MAX_ARRAY_ELEMENTS {
                    crate::bail!("gguf: array length {len} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}")
                }
                let needed = len.saturating_mul(value_type.min_disk_size(magic));
                let remaining = remaining_bytes(reader, file_size)?;
                if needed > remaining {
                    crate::bail!(
                        "gguf: array of {len} elements needs at least {needed} bytes, only {remaining} remaining"
                    )
                }
                let mut vs = Vec::new();
                for _ in 0..len {
                    vs.push(Value::read(
                        reader,
                        value_type,
                        magic,
                        depth + 1,
                        file_size,
                    )?)
                }

View on GitHub (pinned to d5fee525bf)

Solutions

Treat the file as corrupt: verify its checksum and re-download from a trusted source.
Confirm the file opens correctly in a reference reader (llama.cpp's gguf tooling) to rule out parser mismatch.
Update candle — the cap is part of hardening fixes in recent versions.
If you genuinely need bigger arrays, patch the constant and rebuild candle (weigh the DoS tradeoff).

Example fix

// before
let content = gguf_file::Content::read(&mut reader)?;
// after
let meta = std::fs::metadata(path)?;
println!("file size {}", meta.len()); // sanity-check before parsing
let content = gguf_file::Content::read(&mut reader)?;

Defensive patterns

Strategy: validation

Validate before calling

// pre-screen: refuse implausibly huge metadata arrays relative to file size
let meta = std::fs::metadata(path)?;
if meta.len() < 64 || meta.len() > MAX_ACCEPTED_GGUF_SIZE { bail!("gguf size out of range"); }

Try / catch

match gguf_file::Content::read(&mut reader) {
    Ok(c) => c,
    Err(e) if e.to_string().contains("exceeds max") => {
        eprintln!("GGUF declares an oversized array — likely corrupt or hostile");
        return Err(Error::Msg("invalid gguf array length".into()));
    }
    Err(e) => return Err(e.into()),
}

Prevention

Never parse untrusted GGUF files without validation; the cap is a DoS guard
Verify checksums from the model publisher
Keep candle updated so the GGUF_MAX_ARRAY_ELEMENTS guard is present
Pre-screen with an independent GGUF inspector for files from unknown sources

When it happens

Trigger: Parsing a GGUF file whose metadata array header declares an element count above the library's maximum — seen with corrupted length bytes, adversarially crafted files, or files larger than the cap permits.

Common situations: Untrusted model downloads processed without validation; corrupted vocabulary arrays (tokenizer.ggml.tokens) where the u64 length field is garbage; fuzz-tested inputs.

Related errors

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