{
  "id": "llm/llama-cpp-gguf-model-mismatch",
  "signature": "llama_cpp.llama_cpp.LlamaError: Model file 'model.gguf' is not a valid GGUF file or is corrupted. Expected magic number 0x46554747, got 0x00000000.",
  "signature_zh": "llama_cpp.llama_cpp.LlamaError: 模型文件 'model.gguf' 不是有效的 GGUF 文件或已损坏。预期幻数 0x46554747，实际 0x00000000。",
  "regex": "llama_cpp\\.llama_cpp\\.LlamaError.*not a valid GGUF file or is corrupted",
  "domain": "llm",
  "category": "install_error",
  "subcategory": null,
  "root_cause": "The GGUF model file is either incomplete (truncated download), corrupted during transfer, or is not actually a GGUF file (e.g., a PyTorch checkpoint or a different format renamed to .gguf).",
  "root_cause_type": "generic",
  "root_cause_zh": "GGUF 模型文件要么不完整（下载截断），在传输过程中损坏，或者实际上不是 GGUF 文件（例如，PyTorch 检查点或其他格式重命名为 .gguf）。",
  "versions": [
    {
      "version": "llama-cpp-python==0.2.60",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "llama-cpp-python==0.2.70",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "llama.cpp==b2775",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The error is in the model file, not the library. Reinstalling the package does not repair a corrupted or invalid GGUF file.",
      "fail_rate": 0.98,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "llama.cpp only supports GGUF format. Changing the extension doesn't convert the file; the library will still try to parse it as GGUF and fail.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The quantization level is embedded in the GGUF file itself. You cannot change the quantization by renaming or modifying metadata; you need the correct GGUF file for that quantization.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Verify the GGUF file integrity using the sha256 checksum provided by the model source (e.g., Hugging Face). Re-download the file if the checksum doesn't match: `sha256sum model.gguf` then compare with the published hash. Example: `curl -L -o model.gguf https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf`.",
      "success_rate": 0.98,
      "how": "Verify the GGUF file integrity using the sha256 checksum provided by the model source (e.g., Hugging Face). Re-download the file if the checksum doesn't match: `sha256sum model.gguf` then compare with the published hash. Example: `curl -L -o model.gguf https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use the `convert.py` script from llama.cpp to convert a PyTorch checkpoint to GGUF: `python convert.py --outfile model.gguf /path/to/pytorch/model`.",
      "success_rate": 0.85,
      "how": "Use the `convert.py` script from llama.cpp to convert a PyTorch checkpoint to GGUF: `python convert.py --outfile model.gguf /path/to/pytorch/model`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Check the first few bytes of the file to confirm it's a GGUF: `head -c 4 model.gguf | od -A x -t x1z`. Expected output: `000000 47 47 55 46 >GGUF<`. If it shows zeros or other values, the file is corrupted or not GGUF.",
      "success_rate": 0.9,
      "how": "Check the first few bytes of the file to confirm it's a GGUF: `head -c 4 model.gguf | od -A x -t x1z`. Expected output: `000000 47 47 55 46 >GGUF<`. If it shows zeros or other values, the file is corrupted or not GGUF.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用模型源（例如 Hugging Face）提供的 sha256 校验和验证 GGUF 文件完整性。如果校验和不匹配，则重新下载文件：`sha256sum model.gguf` 然后与发布的哈希值进行比较。示例：`curl -L -o model.gguf https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf`。",
    "使用 llama.cpp 的 `convert.py` 脚本将 PyTorch 检查点转换为 GGUF：`python convert.py --outfile model.gguf /path/to/pytorch/model`。",
    "检查文件的前几个字节以确认它是 GGUF：`head -c 4 model.gguf | od -A x -t x1z`。预期输出：`000000 47 47 55 46 >GGUF<`。如果显示为零或其他值，则文件已损坏或不是 GGUF。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://github.com/ggerganov/llama.cpp/blob/master/docs/development/gguf.md",
  "official_doc_section": null,
  "error_code": "LLAMA-CPP-ERR-0003",
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.92,
  "resolvable": "true",
  "first_seen": "2024-03-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}