janhq/jan · error · KVCacheError::HeadCountInvalid

Invalid metadata: head_count not found or invalid

Error message

Invalid metadata: head_count not found or invalid

What it means

`KVCacheError::HeadCountInvalid` — the estimator could not find or parse the attention head count (e.g. `llama.attention.head_count`). Head count divides the embedding dimension to compute per-head size and is required for accurate KV-cache sizing.

Source

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

#[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())
    }
}


#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize)]

View on GitHub (pinned to fad3f12a14)

Solutions

1. Dump `<arch>.attention.*` keys and confirm both `head_count` and `head_count_kv` are present for GQA models.
2. Add fallbacks for synonym keys across architectures.
3. Parse defensively (trim, float-tolerant).
4. Re-download or use a known-good GGUF if metadata is genuinely incomplete.

Example fix

// before
let h: u64 = meta.metadata.get(&format!("{}.attention.head_count", arch))
    .ok_or(KVCacheError::HeadCountInvalid)?
    .parse().map_err(|_| KVCacheError::HeadCountInvalid)?;

// after - default head_count_kv to head_count when absent (MHA fallback)
let h: u64 = meta.metadata.get(&format!("{}.attention.head_count", arch))
    .ok_or(KVCacheError::HeadCountInvalid)?
    .trim().parse().map_err(|_| KVCacheError::HeadCountInvalid)?;

fn head_counts(meta: &GgufMetadata, arch: &str) -> Option<(u64, u64)> {
    let h = meta.metadata.get(&format!("{arch}.attention.head_count"))?.trim().parse::<u64>().ok()?;
    let h_kv = meta.metadata.get(&format!("{arch}.attention.head_count_kv"))
        .and_then(|s| s.trim().parse::<u64>().ok())
        .unwrap_or(h);
    Some((h, h_kv))
}

null

match estimate_kv_cache(&meta) {
    Ok(est) => Ok(est),
    Err(KVCacheError::HeadCountInvalid) => Err(UserError::UnsupportedModel("missing head_count".into())),
    Err(e) => Err(e.into()),
}

When it happens

Trigger: The `<arch>.attention.head_count` (or equivalent) key is missing, or its value does not parse to an integer. Some architectures split this into `head_count` and `head_count_kv`; absence of either relevant one can produce this error depending on which lookup fires first.

Common situations: Architecture-specific key naming differences (GQA models expose `head_count_kv` separately); a stripped-metadata GGUF; an architecture the lookup was not written to handle. Models with grouped-query attention must expose both head counts.

Related errors

• Invalid metadata: architecture not found
• Invalid metadata: block_count not found or invalid
• Invalid metadata: embedding_length not found or invalid
• Invalid metadata: context_length not found or invalid
• Error reading metadata entry {}: {}

AI-assisted analysis of janhq/jan@fad3f12a14 (2026-08-12). Data as JSON: /api/errors/6a05052a8cec3cfa. Report an issue: GitHub.