gguf: value nesting depth exceeds max {GGUF_MAX_VALUE_DEPTH}

Error message

gguf: value nesting depth exceeds max {GGUF_MAX_VALUE_DEPTH}

What it means

Value::read enforces a maximum nesting depth (GGUF_MAX_VALUE_DEPTH) when parsing GGUF metadata arrays, and throws this when the depth limit is exceeded. It protects the parser from stack overflow / runaway recursion on maliciously or accidentally nested array-of-array structures. This is a deliberate safety guard, not a data-conversion failure.

Source

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

        }
    }

    pub fn to_string(&self) -> Result<&String> {
        match self {
            Self::String(v) => Ok(v),
            v => crate::bail!("not a string {v:?}"),
        }
    }

    fn read<R: std::io::Read + std::io::Seek>(
        reader: &mut R,
        value_type: ValueType,
        magic: &VersionedMagic,
        depth: usize,
        file_size: u64,
    ) -> Result<Self> {
        if depth > GGUF_MAX_VALUE_DEPTH {
            crate::bail!("gguf: value nesting depth exceeds max {GGUF_MAX_VALUE_DEPTH}")
        }
        let v = match value_type {
            ValueType::U8 => Self::U8(reader.read_u8()?),
            ValueType::I8 => Self::I8(reader.read_i8()?),
            ValueType::U16 => Self::U16(reader.read_u16::<LittleEndian>()?),
            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)?),

View on GitHub (pinned to d5fee525bf)

Solutions

Verify the file with its SHA256/checksum against the publisher's value — the file is likely corrupt.
Re-download the GGUF file from a trusted source.
Keep candle updated: the depth cap was added as a hardening fix; older parsers would have crashed instead.
If you legitimately need deeper nesting, raise GGUF_MAX_VALUE_DEPTH in a patched build (rarely advisable).

Example fix

// before
let content = gguf_file::Content::read(&mut reader)?; // panics/bails on corrupt file
// after
let file_hash = sha256_file(path)?;
if file_hash != EXPECTED_SHA256 { bail!("GGUF file is corrupt"); }
let content = gguf_file::Content::read(&mut reader)?;

Defensive patterns

Strategy: validation

Validate before calling

// checksum + size sanity check before parsing untrusted GGUF files
let digest = sha256_hex(File::open(path)?)?;
if !TRUSTED_SHA256.contains(&digest.as_str()) { bail!("untrusted GGUF file"); }

Try / catch

let content = match gguf_file::Content::read(&mut reader) {
    Ok(c) => c,
    Err(e) if e.to_string().contains("nesting depth") => {
        eprintln!("GGUF file corrupt/recursive: {e}");
        return Err(Error::Msg("invalid gguf file".into()));
    }
    Err(e) => return Err(e.into()),
};

Prevention

Only parse GGUF files from trusted sources or with verified checksums
Update candle to versions with the depth-limit hardening
Validate file size vs header claims before parsing
Use a reference tool (llama.cpp gguf dump) to pre-screen unknown files

When it happens

Trigger: Reading a GGUF file whose array element types recurse (array containing arrays) beyond the configured depth limit — typically only possible with a crafted or corrupted file since legitimate GGUF metadata is shallow.

Common situations: Loading a truncated or bit-rotted GGUF file where array headers are misread so element type bytes cascade into nested arrays; processing untrusted model files from unknown sources; fuzzing or adversarial inputs.

Related errors

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