janhq/jan · error · KVCacheError

ContextLengthInvalid

ContextLengthInvalid

Error message

Invalid metadata: context_length not found or invalid

What it means

KVCacheError::ContextLengthInvalid is raised when GGUF metadata lacks a valid `context_length` key. The KV-cache needs the model's maximum context length to allocate and bound the cache, so it refuses to proceed when the key is missing or unreadable. It indicates a defective or unsupported GGUF file.

Solutions

1. Re-download the model file and verify checksum integrity.
2. Check metadata via gguf-dump for a present, positive `context_length` value.
3. Re-convert the source model with up-to-date llama.cpp conversion tooling.
4. Patch/extend the plugin's metadata reader if the model legitimately stores context length under a different key.

Example fix

// before: silently assuming defaults
let ctx = md.context_length();

// after
let ctx = md.get("llama.context_length")
    .copied()
    .filter(|v| *v > 0)
    .ok_or_else(|| anyhow!("GGUF missing context_length; re-download/re-convert the model"))?;

// Rust: verify context_length before KV-cache allocation
fn has_context_length(md: &GgufMetadata, arch: &str) -> bool {
    md.get_u64(&format!("{arch}.context_length")).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::ContextLengthInvalid) => anyhow::bail!("GGUF missing context_length; use a properly converted model"),
    other => other?,
}

When it happens

Trigger: Loading a GGUF model without `{arch}.context_length` metadata, or with a value that cannot be parsed as the expected integer, during KV-cache creation.

Common situations: Bad downloads; models edited/stripped with third-party tools; very old GGUF files predating the context_length key; converters that don't write context settings.

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

• BlockCountInvalid
• 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/c62c9237f199d1f4. Report an issue: GitHub.

Appendix: source

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

    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)]
pub enum ModelSupportStatus {
    #[serde(rename = "RED")]
    Red,
    #[serde(rename = "YELLOW")]

View on GitHub (pinned to 7205d770c1)