# Why llama.cpp fails to load a GGUF file, and how to fix it > Source: https://netray.co/troubleshoot/llama-cpp-gguf-load-failed > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: On-Prem AI Troubleshooting ## Short answer A GGUF load failure in llama.cpp is almost always one of three things: the file was truncated or corrupted during download, the file uses a quantization or metadata format newer than your llama.cpp build supports, or the model was split into multiple GGUF shards and only some of them were downloaded. Verify the file size and checksum first, then check your llama.cpp version against the GGUF version the file requires. ## Error Title llama.cpp fails to load a GGUF model file ## Error Signature error loading model: unexpectedly reached end of file ## Alternate Signatures - gguf_init_from_file: invalid magic number - llama_model_load: error loading model: missing tensor - failed to load model 'model.gguf' ## Category local-runtime ## Stack - llama-cpp - ollama ## Affects Any llama.cpp build or Ollama version loading a GGUF file, most common with large downloads and split or sharded models ## Quick Fix ### Fastest path to a loading model **Steps:** - Check the downloaded file size against the size listed on the source; a mismatch means a truncated download. - Re-download the file with a tool that resumes and verifies, such as huggingface-cli download or wget -c, rather than a browser download for large files. - If the model card lists multiple split GGUF files (part-00001-of-00003 style names), confirm every shard is present in the same directory. - Update llama.cpp or Ollama to the latest release, since older builds cannot read newer GGUF metadata versions or newer quant types. - Verify the file with a checksum if one is published, and only then retry loading. ## Symptoms - Loading fails immediately with an end-of-file or truncated read error rather than a clear file-not-found error - The error mentions an invalid magic number or unrecognized GGUF version - The model loads on one machine's llama.cpp build but fails on another with an older version installed - Downloading again from scratch fixes the problem, implying the first download was incomplete ## Causes ### Corrupted or truncated download **Likelihood:** most-common **Explanation:** GGUF files for larger models are many gigabytes, and interrupted downloads, flaky connections, or browser downloads that silently stop early leave a file that looks present on disk but is missing data at the end; llama.cpp's parser reads a fixed structure and hits an unexpected end of file when the tensor data runs short. **Fix:** Compare the file size on disk against the expected size from the source, and re-download using a tool built for large, resumable transfers rather than a plain browser download. **Commands:** - ls -la model.gguf - huggingface-cli download --local-dir . - wget -c ### GGUF format or quant type newer than the installed llama.cpp/Ollama version supports **Likelihood:** common **Explanation:** The GGUF format and the set of supported quantization types have evolved across llama.cpp releases; a file quantized with a newer scheme or metadata version cannot be parsed by an older llama.cpp binary, which reports it as an invalid or unsupported file rather than explaining the version mismatch. **Fix:** Update llama.cpp (rebuild from the latest source) or Ollama to the latest release, since GGUF forward compatibility depends entirely on the reading binary supporting the format the file was written with. **Commands:** - git pull && cmake --build build --config Release - ollama --version ### Split GGUF model missing one or more shard files **Likelihood:** common **Explanation:** Very large models are distributed as multiple GGUF files named with a part index, and llama.cpp needs every shard present in the same directory to reconstruct the full tensor set; downloading only the first file, which is common when someone grabs just the file that looks like the main one, produces a load failure once the parser reaches data that lives in a missing shard. **Fix:** Download every split file listed on the model page, keep them in the same directory with their original names, and load by pointing at the first shard, letting llama.cpp locate the rest automatically. **Commands:** - huggingface-cli download --local-dir . --include '*.gguf' ### Wrong file passed as the model path **Likelihood:** occasional **Explanation:** Pointing llama.cpp at a non-GGUF file (a raw safetensors checkpoint, a README, or a partially extracted archive) with a .gguf extension added by mistake produces the same generic load error, since the parser fails the same way whether the content is corrupt or simply not GGUF at all. **Fix:** Confirm the file is actually a GGUF file by checking its header bytes, and re-download the correct converted GGUF artifact rather than a raw model checkpoint. **Commands:** - xxd model.gguf | head -1 ### Filesystem or disk issue causing silent data corruption **Likelihood:** rare **Explanation:** On rare occasions a failing disk, a network filesystem hiccup, or an interrupted copy between machines corrupts bytes in the middle of an otherwise complete-looking file, which can produce load errors that look identical to a truncated download but are not fixed by simply checking the file size. **Fix:** Verify the file against a published checksum if available, and copy it fresh from the original source to a different disk to rule out local storage corruption. **Commands:** - sha256sum model.gguf ## Diagnostics ### Compare file size to expected size **Command:** ls -la model.gguf **Interpretation:** A size noticeably smaller than what the source lists is a strong signal of a truncated download; re-download rather than debugging further. ### Check the GGUF magic bytes **Command:** xxd model.gguf | head -1 **Interpretation:** A valid GGUF file starts with the ASCII bytes GGUF; anything else means the file is not a GGUF file at all, or is corrupted at the very start. ### Check installed llama.cpp/Ollama version **Command:** ollama --version **Interpretation:** Compare against the release notes or model card date for the GGUF file; a much older runtime version is a common reason newer quant types fail to load. ### Verify checksum if published **Command:** sha256sum model.gguf **Interpretation:** A mismatch against the published hash confirms corruption somewhere in the download or transfer path, independent of file size. ## Prevention - Always download large GGUF files with a resumable, verifying tool (huggingface-cli, wget -c, aria2c) instead of a browser tab. - Check published file sizes and checksums as a standard step before attempting to load any new model file. - Keep llama.cpp and Ollama reasonably current, especially before trying a model released after your current installed version. - For split models, download and verify every shard together as one atomic step, not incrementally over time. ## When To Escalate If you are repeatedly hitting corrupted downloads or version mismatches across an air-gapped or bandwidth-constrained environment, it is worth building an internal, checksum-verified model artifact store that your team pulls from, rather than each engineer re-downloading multi-gigabyte files from the public internet individually. ## Faq ### How do I know if a GGUF file is split into multiple parts? **Answer:** The filenames follow a pattern like model-00001-of-00003.gguf, with the total shard count in the name. If the model card or repository lists more than one .gguf file for a single model, you need all of them present together, not just the first. ### Can I fix a corrupted GGUF file without re-downloading it? **Answer:** Generally no. GGUF corruption from a truncated or interrupted transfer means missing or wrong bytes, which cannot be reconstructed locally. Re-downloading, ideally with a tool that verifies integrity, is the reliable fix. ### Does Ollama use the same GGUF format as raw llama.cpp? **Answer:** Yes, Ollama is built on llama.cpp under the hood and uses the same GGUF file format, so a GGUF load failure has the same set of likely causes whether you hit it through Ollama or by running llama.cpp's binaries directly. ## Search terms gguf load failed, llama.cpp unexpectedly reached end of file, gguf invalid magic number, gguf split files, ollama gguf corrupted, gguf missing tensor --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json