janhq/jan · error · io::Error

Error reading metadata entry

Error message

Error reading metadata entry {}: {}

What it means

read_header wraps any failure from read_metadata_entry for KV entry i with its index, so the offending metadata record is identified. The inner error is usually a nested string/value failure (key read, unknown value type, oversized string/array) or plain I/O failure.

Solutions

1. Read the inner error text (after the index) to identify the sub-cause - unknown value type, string length, or I/O error
2. Re-download the file and verify its checksum
3. If the inner error is 'Unknown GGUF value type', update the parser or re-export the model with an older gguf version
4. Cross-check with llama.cpp's gguf_dump to see which KV entry is malformed

Example fix

// before
let meta = read_gguf_metadata(file)?; // Error reading metadata entry 7: ...
// after
match read_gguf_metadata(file) {
    Ok(m) => m,
    Err(e) if e.to_string().contains("metadata entry") => {
        log::warn!("GGUF KV section corrupt: {e}; refusing model");
        anyhow::bail!("model file damaged - re-download")
    }
    Err(e) => return Err(e.into()),
}

match read_gguf_metadata(file) {
    Err(e) if e.to_string().contains("metadata entry") => {
        // e.g. 'Error reading metadata entry 7: ...' - index names the bad KV record
        eprintln!("GGUF KV section corrupt: {e}");
    }
    other => other?,
}

When it happens

Trigger: Calling read_gguf_metadata or find_gguf_tensors on a file whose KV metadata section is truncated, contains an unknown value-type tag, or has an oversized string/array - the inner message names the exact sub-cause.

Common situations: Corrupted model downloads, files written by newer GGUF writers using value types this parser does not know, truncated transfers, tooling that pads or edits KV sections.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Array length is unreasonably large
• Failed to read key for metadata entry
• Failed to read name for tensor
• String length is unreasonably large
• tensor claims dimensions

AI-assisted analysis of janhq/jan@7205d770c1 (2026-09-17). Data as JSON: /api/errors/240dadb2d46d601f. Report an issue: GitHub.

Appendix: source

Thrown at src-tauri/plugins/tauri-plugin-llamacpp/src/gguf/helpers.rs:113

    if &magic != b"GGUF" {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            "Not a GGUF file",
        ));
    }

    let version = file.read_u32::<LittleEndian>()?;
    let tensor_count = file.read_u64::<LittleEndian>()?;
    let metadata_count = file.read_u64::<LittleEndian>()?;

    let mut metadata_map = std::collections::HashMap::new();
    for i in 0..metadata_count {
        match read_metadata_entry(file, i) {
            Ok((key, value)) => {
                metadata_map.insert(key, value);
            }
            Err(e) => {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    format!("Error reading metadata entry {}: {}", i, e),
                ));
            }
        }
    }

    Ok(GgufMetadata {
        version,
        tensor_count,
        metadata: metadata_map,
    })
}

fn read_metadata_entry<R: Read + Seek + ReadBytesExt>(
    reader: &mut R,
    index: u64,
) -> io::Result<(String, String)> {

View on GitHub (pinned to 7205d770c1)