huggingface/candle · error

unrecognized value-type {v:#08x}

Error message

unrecognized value-type {v:#08x}

What it means

GGUF files encode a per-value type tag in metadata entries. When reading the file, the declared numeric tag is matched against known GGUF value types (u8..f64, bool, string, array). If the tag does not map to any known type, candle refuses to parse the file because it cannot know how to decode the following bytes.

Source

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

}

impl ValueType {
    fn from_u32(v: u32) -> Result<Self> {
        let v = match v {
            0 => Self::U8,
            1 => Self::I8,
            2 => Self::U16,
            3 => Self::I16,
            4 => Self::U32,
            5 => Self::I32,
            6 => Self::F32,
            7 => Self::Bool,
            8 => Self::String,
            9 => Self::Array,
            10 => Self::U64,
            11 => Self::I64,
            12 => Self::F64,
            v => crate::bail!("unrecognized value-type {v:#08x}"),
        };
        Ok(v)
    }

    fn to_u32(self) -> u32 {
        match self {
            Self::U8 => 0,
            Self::I8 => 1,
            Self::U16 => 2,
            Self::I16 => 3,
            Self::U32 => 4,
            Self::I32 => 5,
            Self::F32 => 6,
            Self::Bool => 7,
            Self::String => 8,
            Self::Array => 9,
            Self::U64 => 10,
            Self::I64 => 11,

View on GitHub (pinned to d5fee525bf)

Solutions

1. Regenerate or re-download the GGUF file with a converter matching candle's supported GGUF spec version
2. Check the file magic/size to confirm it is a valid GGUF file and not truncated
3. Update candle-core in case a newer release supports additional value types

Example fix

// before
let model = GgufFile::from_reader(&mut File::open("model.gguf")?)?;
// after
// verify file integrity first, and use a converter version candle supports
let meta = std::fs::metadata("model.gguf")?;
assert!(meta.len() > 32, "file too small to be valid gguf");
let model = GgufFile::from_reader(&mut File::open("model.gguf")?)?;

let mut f = File::open("model.gguf")?;
let mut magic = [0u8; 4];
f.read_exact(&mut magic)?;
if &magic != b"GGUF" { return Err(anyhow!("not a gguf file")); }
// trust only files from verified sources with matching checksums

match GgufFile::from_reader(&mut reader) {
    Ok(g) => g,
    Err(e) if e.to_string().contains("unrecognized value-type") => {
        eprintln!("GGUF file uses an unsupported value type; re-convert with a compatible llama.cpp version");
        return Err(e.into());
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Loading a GGUF file whose metadata kv entry contains a value-type tag outside 0-12, typically produced by a newer GGUF spec revision or a corrupted/truncated header.

Common situations: Using a GGUF file written by a newer llama.cpp/converter version that introduced a new value type; hand-edited or corrupted model files; wrong file downloaded (not actually GGUF).

Related errors

• gguf: tensor_count {tensor_count} exceeds max {GGUF_MAX_ARRA
• gguf: metadata_kv_count {metadata_kv_count} exceeds max {GGU
• gguf: header declares {tensor_count} tensors and {metadata_k
• gguf: tensor '{tensor_name}' has {n_dimensions} dimensions,
• {} is a dummy type and does not support parsing

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