{"record":{"id":"6a05052a8cec3cfa","repo":"janhq/jan","slug":"invalid-metadata-head-count-not-found-or-invalid","errorCode":null,"errorMessage":"Invalid metadata: head_count not found or invalid","messagePattern":"Invalid metadata: head_count not found or invalid","errorType":"error_code","errorClass":"KVCacheError::HeadCountInvalid","httpStatus":null,"severity":"error","filePath":"src-tauri/plugins/tauri-plugin-llamacpp/src/gguf/types.rs","lineNumber":67,"sourceCode":"#[derive(Serialize)]\npub struct GgufMetadata {\n    pub version: u32,\n    pub tensor_count: u64,\n    pub metadata: HashMap<String, String>,\n}\n\n#[derive(Debug, Serialize, Deserialize)]\npub struct KVCacheEstimate {\n    pub size: u64,\n    pub per_token_size: u64,\n}\n#[derive(Debug, thiserror::Error)]\npub enum KVCacheError {\n    #[error(\"Invalid metadata: architecture not found\")]\n    ArchitectureNotFound,\n    #[error(\"Invalid metadata: block_count not found or invalid\")]\n    BlockCountInvalid,\n    #[error(\"Invalid metadata: head_count not found or invalid\")]\n    HeadCountInvalid,\n    #[error(\"Invalid metadata: embedding_length not found or invalid\")]\n    EmbeddingLengthInvalid,\n    #[error(\"Invalid metadata: context_length not found or invalid\")]\n    ContextLengthInvalid,\n}\n\nimpl serde::Serialize for KVCacheError {\n    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>\n    where\n        S: serde::Serializer,\n    {\n        serializer.serialize_str(&self.to_string())\n    }\n}\n\n\n#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize)]","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/janhq/jan/blob/fad3f12a147d138388a66f0d92a02b2675f65294/src-tauri/plugins/tauri-plugin-llamacpp/src/gguf/types.rs#L49-L85","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Dump `<arch>.attention.*` keys and confirm both `head_count` and `head_count_kv` are present for GQA models.","Add fallbacks for synonym keys across architectures.","Parse defensively (trim, float-tolerant).","Re-download or use a known-good GGUF if metadata is genuinely incomplete."],"exampleFix":"// before\nlet h: u64 = meta.metadata.get(&format!(\"{}.attention.head_count\", arch))\n    .ok_or(KVCacheError::HeadCountInvalid)?\n    .parse().map_err(|_| KVCacheError::HeadCountInvalid)?;\n\n// after - default head_count_kv to head_count when absent (MHA fallback)\nlet h: u64 = meta.metadata.get(&format!(\"{}.attention.head_count\", arch))\n    .ok_or(KVCacheError::HeadCountInvalid)?\n    .trim().parse().map_err(|_| KVCacheError::HeadCountInvalid)?;","handlingStrategy":"validation","validationCode":"fn head_counts(meta: &GgufMetadata, arch: &str) -> Option<(u64, u64)> {\n    let h = meta.metadata.get(&format!(\"{arch}.attention.head_count\"))?.trim().parse::<u64>().ok()?;\n    let h_kv = meta.metadata.get(&format!(\"{arch}.attention.head_count_kv\"))\n        .and_then(|s| s.trim().parse::<u64>().ok())\n        .unwrap_or(h);\n    Some((h, h_kv))\n}","typeGuard":"null","tryCatchPattern":"match estimate_kv_cache(&meta) {\n    Ok(est) => Ok(est),\n    Err(KVCacheError::HeadCountInvalid) => Err(UserError::UnsupportedModel(\"missing head_count\".into())),\n    Err(e) => Err(e.into()),\n}","preventionTips":["Account for grouped-query attention by reading both head_count and head_count_kv.","Default head_count_kv to head_count for MHA models.","Log attention keys to spot architecture-specific naming."],"tags":["gguf","metadata","attention","kvcache","llamacpp","rust"],"backgroundTag":null,"analyzedSha":"fad3f12a147d138388a66f0d92a02b2675f65294","analyzedAt":"2026-08-12T20:33:47.516Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}