{"record":{"id":"8c172a0f8219e8ce","repo":"janhq/jan","slug":"headcountinvalid","errorCode":"HeadCountInvalid","errorMessage":"Invalid metadata: head_count not found or invalid","messagePattern":"Invalid metadata: head_count not found or invalid","errorType":"error_code","errorClass":"KVCacheError","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/7205d770c1e097c3daf35a911176410e93bc5564/src-tauri/plugins/tauri-plugin-llamacpp/src/gguf/types.rs#L49-L85","documentation":"KVCacheError::HeadCountInvalid is raised when the GGUF metadata lacks a valid `head_count` (attention head count) key. The KV-cache construction needs this to dimension per-head tensors, so it rejects the model if the key is missing or unreadable. Like the other Invalid-metadata variants, it points at a bad or unsupported GGUF file.","triggerScenarios":"Loading a GGUF model whose metadata map is missing `{arch}.head_count`, or whose value cannot be parsed into the expected integer type during KV-cache setup.","commonSituations":"Corrupt or incomplete model downloads; models converted by third-party tools that omit head_count; architectures whose key prefix differs from what the reader expects.","solutions":["Re-download the GGUF file from the original source and verify integrity.","Dump metadata (e.g. gguf-dump) and confirm `head_count` is present with a sane positive value.","Re-convert the model with current llama.cpp conversion scripts to regenerate complete metadata.","Update the plugin if the model uses a newer architecture naming scheme it doesn't recognize."],"exampleFix":"// before\nlet cache = kv_cache::from_gguf(&model_path).unwrap();\n\n// after\nmatch kv_cache::from_gguf(&model_path) {\n    Ok(c) => c,\n    Err(KVCacheError::HeadCountInvalid) => {\n        anyhow::bail!(\"model file lacks head_count metadata; re-download or re-convert the GGUF\")\n    }\n    Ok => unreachable!(),\n}","handlingStrategy":"validation","validationCode":"// Rust: check head_count key before loading\nfn has_head_count(md: &GgufMetadata, arch: &str) -> bool {\n    md.get_u64(&format!(\"{arch}.head_count\")).map(|v| v > 0).unwrap_or(false)\n}","typeGuard":"fn valid_u64(v: Option<&u64>) -> bool {\n    matches!(v, Some(n) if *n > 0)\n}","tryCatchPattern":"match kv_cache::from_gguf(&path) {\n    Err(KVCacheError::HeadCountInvalid) => anyhow::bail!(\"GGUF missing head_count; re-download model\"),\n    other => other?,\n}","preventionTips":["Validate model metadata keys once at app startup for bundled models.","Re-convert legacy GGUF files with updated llama.cpp scripts.","Log which metadata keys are missing to speed up diagnosis."],"tags":["gguf","rust","model-loading","metadata"],"backgroundTag":"missing-required-config-field","analyzedSha":"7205d770c1e097c3daf35a911176410e93bc5564","analyzedAt":"2026-09-17T14:27:30.100Z","contentChangedAt":"2026-09-17T14:27:30.100Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}