janhq/jan · error · KVCacheError

BlockCountInvalid

BlockCountInvalid

Error message

Invalid metadata: block_count not found or invalid

What it means

KVCacheError::BlockCountInvalid is raised when a GGUF model file's metadata does not contain a valid `block_count` key. The KV-cache setup code in the llamacpp plugin requires this value to size the cache and fails fast if it is missing or not a readable integer. It indicates a malformed, truncated, or unsupported GGUF file rather than a bug in calling code.

Solutions

1. Re-download the GGUF model file and verify its checksum; a truncated download commonly drops trailing metadata.
2. Inspect the file with `gguf-dump` (or llama.cpp's gguf tooling) to confirm the `block_count` metadata key exists.
3. Re-convert the model to GGUF with an up-to-date llama.cpp `convert*.py` script so all required metadata keys are written.
4. If the file is fine, update the tauri-plugin-llamacpp plugin in case it lacks support for the model's architecture prefix.

Example fix

// before: trusting an arbitrary downloaded GGUF
let cache = kv_cache::from_gguf(path)?;

// after: verify metadata first
let md = gguf::read_metadata(path)?;
if md.get("llama.block_count").is_none() {
    return Err(anyhow!("GGUF file missing block_count; re-download or re-convert"));
}
let cache = kv_cache::from_gguf(path)?;

// Rust: validate GGUF metadata before KV-cache construction
fn has_block_count(md: &GgufMetadata, arch: &str) -> bool {
    md.get_u64(&format!("{arch}.block_count")).map(|v| v > 0).unwrap_or(false)
}

fn valid_u64(v: Option<&u64>) -> bool {
    matches!(v, Some(n) if *n > 0)
}

match kv_cache::from_gguf(&path) {
    Err(KVCacheError::BlockCountInvalid) => eprintln!("bad GGUF: missing block_count"),
    other => other?,
}

When it happens

Trigger: Loading a GGUF model whose metadata map lacks `{arch}.block_count` (e.g. corrupted download, non-standard exporter, or an architecture the reader doesn't recognize), or where the value cannot be read as u64.

Common situations: Partially downloaded or hand-truncated GGUF files; models produced by unusual quantization/conversion tools; renamed architecture prefixes in metadata keys; very old GGUF revisions.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• ContextLengthInvalid
• EmbeddingLengthInvalid
• HeadCountInvalid
• Invalid metadata: architecture not found
• Invalid metadata: block_count not found or invalid

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

Appendix: source

Thrown at src-tauri/plugins/tauri-plugin-llamacpp/src/gguf/types.rs:65

}

#[derive(Serialize)]
pub struct GgufMetadata {
    pub version: u32,
    pub tensor_count: u64,
    pub metadata: HashMap<String, String>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct KVCacheEstimate {
    pub size: u64,
    pub per_token_size: u64,
}
#[derive(Debug, thiserror::Error)]
pub enum KVCacheError {
    #[error("Invalid metadata: architecture not found")]
    ArchitectureNotFound,
    #[error("Invalid metadata: block_count not found or invalid")]
    BlockCountInvalid,
    #[error("Invalid metadata: head_count not found or invalid")]
    HeadCountInvalid,
    #[error("Invalid metadata: embedding_length not found or invalid")]
    EmbeddingLengthInvalid,
    #[error("Invalid metadata: context_length not found or invalid")]
    ContextLengthInvalid,
}

impl serde::Serialize for KVCacheError {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(&self.to_string())
    }
}

View on GitHub (pinned to 7205d770c1)