huggingface/candle · error

Invalid nval for entry {}: {}

Error message

Invalid nval for entry {}: {}

What it means

Each imatrix entry declares how many f32 values (nval) follow. A value < 1 is invalid since an importance matrix entry must contain at least one value; candle bails with the entry index and the bogus value. This signals corruption or a format mismatch in the imatrix file.

Source

Thrown at candle-core/src/quantized/imatrix_file.rs:69

        let mut name_buf = vec![0u8; len];
        cursor.read_exact(&mut name_buf).map_err(|e| {
            crate::Error::msg(format!("Failed to read name for entry {}: {}", i + 1, e))
        })?;
        let name = String::from_utf8(name_buf).map_err(|e| {
            crate::Error::msg(format!("Invalid UTF-8 name for entry {}: {}", i + 1, e))
        })?;

        // Read ncall and nval
        let ncall = cursor.read_i32::<LittleEndian>().map_err(|e| {
            crate::Error::msg(format!("Failed to read ncall for entry {}: {}", i + 1, e))
        })? as usize;

        let nval = cursor.read_i32::<LittleEndian>().map_err(|e| {
            crate::Error::msg(format!("Failed to read nval for entry {}: {}", i + 1, e))
        })? as usize;

        if nval < 1 {
            crate::bail!("Invalid nval for entry {}: {}", i + 1, nval);
        }

        let mut data = Vec::with_capacity(nval);
        for _ in 0..nval {
            let v = cursor.read_f32::<LittleEndian>().unwrap();
            if ncall == 0 {
                data.push(v);
            } else {
                data.push(v / ncall as f32);
            }
        }
        all_data.insert(name, data);
    }

    Ok(all_data)
}

View on GitHub (pinned to d5fee525bf)

Solutions

1. Regenerate or re-download the imatrix file and verify it was produced by a compatible tool version
2. Verify the file is actually an imatrix file (correct path/format) before loading
3. Check the file for truncation/corruption (size and checksum)

Example fix

// before
let imatrix = load_imatrix("model.gguf")?; // wrong file passed
// after
let imatrix = load_imatrix("model.imatrix")?; // correct imatrix file

let meta = std::fs::metadata("model.imatrix")?;
if meta.len() < 8 {
    return Err(anyhow!("imatrix too small to be valid ({} bytes)", meta.len()));
}
assert_eq!(sha256_file("model.imatrix")?, EXPECTED_SHA256);

match load_imatrix(&fname) {
    Ok(m) => m,
    Err(e) if e.to_string().contains("Invalid nval") => {
        eprintln!("imatrix file corrupt or wrong format; regenerate with a compatible tool");
        return Err(e.into());
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: load_imatrix reading an entry whose nval i32 field is 0 or negative — truncated file, misaligned parsing due to earlier corruption, or a file not actually in imatrix format.

Common situations: Corrupted downloads; passing a regular GGUF or other binary where an imatrix file is expected; imatrix produced by an incompatible tool version.

Related errors

• No data in file {}
• {} is a dummy type and does not support parsing
• gguf: value nesting depth exceeds max {GGUF_MAX_VALUE_DEPTH}
• unexpected bool value {b}
• gguf: array length {len} exceeds max {GGUF_MAX_ARRAY_ELEMENT

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