Ollama Modelfile’s “Invalid File Magic” Error

One line, no traceback, no hint about which file. It is produced by a four-byte comparison at the very start of loading, which is good news: you can reproduce the check yourself in one command and know exactly what you have.

The error

$ ollama create mymodel -f Modelfile
transferring model data
Error: invalid file magic

Newer versions may instead say Error: supplied file was not in GGUF format, which is the same check with clearer wording. Both come from the create step reading the file named by your FROM line, and both fire before any weights are parsed — so the size of the model, the amount of RAM you have and the parameters in the Modelfile are all irrelevant to this failure.

What a file magic is and what Ollama checks

A magic number is a fixed byte sequence at the start of a file that identifies its format. GGUF’s is the four ASCII characters GGUF — bytes 0x47 0x47 0x55 0x46 — followed by a four-byte version number and then the tensor and metadata counts. Ollama reads those first four bytes, compares, and refuses immediately on a mismatch.

That is a deliberately cheap check, and it means the error tells you precisely one thing: the first four bytes were not GGUF. It says nothing about whether the rest of the file is fine. Predecessor formats from the same lineage used ggml, ggmf, ggjt and ggla in the same position, which is why an old download from before the GGUF transition fails here rather than with a version complaint.

Two consequences follow from the check being that cheap, and both are useful. The first is that this error is fast: it appears within a second of running create, before anything is copied into Ollama’s store, so nothing has been half-imported and there is nothing to clean up. The second is that a file which passes the check can still be broken in every other way — the magic says “this claims to be GGUF” and nothing more. A file that passes here and fails later, with a complaint about metadata, architecture or tensor shapes, is a different problem with a different page.

Six things that are there instead

• A Git LFS pointer. Cloning a Hugging Face repository without Git LFS installed leaves you a text file of about 130 bytes beginning version https://git-lfs.github.com/spec/v1 where the weights should be. It has the right name and the right extension and is off by several orders of magnitude in size.
• An HTML page. Downloading with curl without -L, or from a URL that returned 403 or 404, saves the error page under the filename you asked for. The first bytes are <!DO or <htm.
• A truncated download. An interrupted transfer leaves a partial file. If the first four bytes made it, this produces a later parse failure rather than this one — so a magic error plus a plausible file size usually means one of the other causes.
• A sharded GGUF. Large models are published split into model-00001-of-00005.gguf and friends. Ollama has not accepted multi-part GGUF directly; pointing FROM at a shard other than the first is a certain failure, and pointing it at the first has historically failed too.
• The wrong format entirely. A .safetensors or .bin checkpoint renamed to .gguf. Renaming does not convert; conversion is a script.
• An alignment bug in the producing tool. Ollama issue 8456 describes GGUF files whose tensors are not aligned to the value in general.alignment, where the padding at the end is read as the start of a second GGUF and the magic check fails on it. Same message, genuinely different problem: the file is valid to llama.cpp and to LM Studio and fails only here.

Four bytes tell you which

Do the same comparison Ollama does, before changing anything:

# Linux / macOS
head -c 4 model.gguf | xxd
# 00000000: 4747 5546                                GGUF

ls -lh model.gguf
file model.gguf

# Windows PowerShell
Get-Content model.gguf -AsByteStream -TotalCount 4 |
  ForEach-Object { [char]$_ }

If it prints GGUF, the file is a GGUF and you are in the last case above — or pointing FROM at a different file than you think. If it prints vers, you have an LFS pointer. If it prints <!DO, an HTML page. If the size is a few hundred bytes, nothing else needs checking.

Fixing each case

1. LFS pointer: install Git LFS and run git lfs pull in the clone, or skip Git entirely and download the single file over HTTPS. For a large weight file, a direct download is usually the better tool anyway.
2. HTML page: re-download with curl -L and check the status code. If the repository is gated, the 403 is the real message — the licence has to be accepted on the model page with your own account, and there is no way around that which respects the licence. See the gated-download page.
3. Sharded GGUF: merge the shards into one file with llama.cpp’s llama-gguf-split --merge tool, pointing it at the first shard and naming an output file, then point FROM at the merged result.
4. Wrong format: convert properly with llama.cpp’s convert_hf_to_gguf.py, then quantize with llama-quantize if you want a smaller file.
5. Alignment or an old container: re-convert the model with a current llama.cpp, or fetch a copy published more recently. Verify it loads with llama-cli first, which isolates whether the file or Ollama is the problem.

A note on the gated case, because it is the one people try to work around. Several widely used model families require you to accept a licence before the weights are downloadable, and the 403 you get without that acceptance is the licence doing its job rather than an obstacle to be routed past. Accept it on the model page with your own account and use a token; there is no version of this page that recommends anything else.

If you want to isolate whether the file or Ollama is at fault before any of the above, load it with llama.cpp directly. It reads the same container and produces a much more talkative failure — it will tell you the version number it read, the architecture string, and how many tensors it expected. A file that loads under llama-cli and fails under ollama create is the alignment case; a file that fails under both is genuinely not a usable GGUF, and re-downloading is the shortest path.

One last check that catches a surprising number of these: the FROM path is resolved relative to where you run ollama create, not relative to the Modelfile. An absolute path removes the ambiguity, and if the file did not exist at all you would get a different error — so if you are seeing this one, something is definitely there.