{"record":{"id":"dcdb2942a968a2ea","repo":"huggingface/candle","slug":"gguf-metadata-kv-count-metadata-kv-count-exceed","errorCode":null,"errorMessage":"gguf: metadata_kv_count {metadata_kv_count} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}","messagePattern":"gguf: metadata_kv_count (.+?) exceeds max (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"candle-core/src/quantized/gguf_file.rs","lineNumber":484,"sourceCode":"}\n\nimpl Content {\n    pub fn read<R: std::io::Seek + std::io::Read>(reader: &mut R) -> Result<Self> {\n        // Capture the file size once so the bounds checks below don't have to\n        // seek to the end and back on every length-prefixed read.\n        let start = reader.stream_position()?;\n        let file_size = reader.seek(std::io::SeekFrom::End(0))?;\n        reader.seek(std::io::SeekFrom::Start(start))?;\n\n        let magic = VersionedMagic::read(reader)?;\n        let tensor_count = read_length(reader, &magic)?;\n        let metadata_kv_count = read_length(reader, &magic)?;\n\n        if tensor_count > GGUF_MAX_ARRAY_ELEMENTS {\n            crate::bail!(\"gguf: tensor_count {tensor_count} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}\")\n        }\n        if metadata_kv_count > GGUF_MAX_ARRAY_ELEMENTS {\n            crate::bail!(\n                \"gguf: metadata_kv_count {metadata_kv_count} exceeds max {GGUF_MAX_ARRAY_ELEMENTS}\"\n            )\n        }\n\n        // Reject header-declared counts that can't fit in the file at minimum size.\n        // Per-entry minima: a metadata kv is at least `key_len_prefix + u32 value_type\n        // + 1 byte value`; a tensor info is at least `name_len_prefix + u32 n_dims\n        // + u32 dtype + u64 offset`.\n        let prefix = magic.length_prefix_size();\n        let min_per_kv = prefix + 4 + 1;\n        let min_per_tensor = prefix + 4 + 4 + 8;\n        let needed = metadata_kv_count\n            .saturating_mul(min_per_kv)\n            .saturating_add(tensor_count.saturating_mul(min_per_tensor));\n        let remaining = remaining_bytes(reader, file_size)?;\n        if needed > remaining {\n            crate::bail!(\n                \"gguf: header declares {tensor_count} tensors and {metadata_kv_count} metadata entries, needs at least {needed} bytes, only {remaining} remaining\"","sourceCodeStart":466,"sourceCodeEnd":502,"githubUrl":"https://github.com/huggingface/candle/blob/d5fee525bfde3273eb7c9b75fd2bc4937be867ca/candle-core/src/quantized/gguf_file.rs#L466-L502","documentation":"Same guard as tensor_count but applied to the header's metadata_kv_count field. A declared metadata key/value count above GGUF_MAX_ARRAY_ELEMENTS would lead to unbounded allocation/loops, so candle bails before parsing the metadata.","triggerScenarios":"GgufFile::read on a file whose header metadata_kv_count exceeds GGUF_MAX_ARRAY_ELEMENTS — corrupt, truncated, or malicious GGUF file.","commonSituations":"Downloading models over flaky connections without checksum verification; opening arbitrary untrusted .gguf files; mismatched file due to wrong path pointing to a non-GGUF binary.","solutions":["Re-download the model file and verify its checksum/integrity","Validate GGUF magic and header before handing to candle","Update candle-core in case a newer release supports additional value types","Do not open GGUF files from untrusted sources"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"let meta = std::fs::metadata(\"model.gguf\")?;\nif meta.len() < 32 || &std::fs::read(\"model.gguf\")?[..4] != *b\"GGUF\" {\n    return Err(anyhow!(\"not a valid gguf file\"));\n}","typeGuard":null,"tryCatchPattern":"match GgufFile::from_reader(&mut reader) {\n    Ok(g) => g,\n    Err(e) if e.to_string().contains(\"metadata_kv_count\") => {\n        eprintln!(\"corrupt gguf header; re-download the file\");\n        return Err(e.into());\n    }\n    Err(e) => return Err(e.into()),\n}","preventionTips":["Verify file integrity (size + checksum) before parsing","Avoid opening untrusted gguf files","Use resumable downloads that verify final size"],"tags":["gguf","corrupt-file","file-format","security"],"backgroundTag":"gguf-header-count-exceeds-limit","analyzedSha":"d5fee525bfde3273eb7c9b75fd2bc4937be867ca","analyzedAt":"2026-09-02T00:15:47.023Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}