koboldcpp.dev

When KoboldCpp can't load your model

Scroll up from "failed to load model": the real reason is a few lines higher. "Cannot find text model file" means a wrong path; "invalid or unsupported model file" means it is not a GGUF; "not within the file bounds" means the download is incomplete; "unknown model architecture" means the model is newer than your KoboldCpp, so update it. We reproduced all four, with exit codes.

Checked against KoboldCpp 1.124.2 · updated 13 Nov 2026
  • lab-lnx: Linux test VM · 4 vCPU · 15 GB · no GPU
  • gha-w25: Windows Server 2025 test machine · 4 vCPU · 16 GB · no GPU
  • gha-w22: Windows Server 2022 test machine · 4 vCPU · 16 GB · no GPU
  • gha-u24: Ubuntu 24.04 test machine · 4 vCPU · 16 GB · no GPU
How we test
On this page
  1. KoboldCpp failed to load model: match your message
  2. “Cannot find text model file”
  3. “invalid or unsupported model file”
  4. “model is corrupted or incomplete”
  5. “unknown model architecture”: your KoboldCpp is older than the model
  6. Models split into several files
  7. Wrong file type
  8. “missing tensor” or “wrong shape”
  9. Vision projector (mmproj) doesn’t match
  10. It starts loading, then runs out of memory
  11. Context size rejected

The result appears here. Nothing you paste leaves this page.

KoboldCpp failed to load model: match your message

Load failures we reproduced (KoboldCpp 1.124.2)
Cannot find text model file: <path>Wrong path2below
invalid or unsupported model fileNot a GGUF3below
data is not within the file bounds, model is corrupted or incompleteIncomplete download3below
unknown model architecture: 'name'Model newer than this KoboldCpp3below
mismatch between text model … and mmprojWrong projector3below
argument --contextsize: must be within [256, 524288]Context value out of range2below

The full list is in the error list.

“Cannot find text model file”

Wrong pathF19 · KoboldCpp 1.124.2 · exit code 2
Cannot find text model file: <path>1
  1. Cannot find text model file: <path>: Printed within 5 to 10 seconds, on every lab OS.

Causes: the file was moved or renamed, a typo, or a launcher field that still holds an old path. Use the launcher’s Browse button to pick the file. A path with spaces and non-ASCII letters loaded on Linux and macOS F91 F102. On a Windows Server the same missing-file message and exit code 2 appeared, but a path with Cyrillic letters crashed with UnicodeEncodeError: 'charmap' codec can't encode characters while the output was redirected to a file; we did not test a normal console, so if you see this error, keep the model in a folder with a plain English name F102.

“invalid or unsupported model file”

Not a GGUFF20, F91 · exit code 3
load_model: error: invalid or unsupported model file '<path>'Load Text Model OK: FalseCould not load text model: <path>

Causes: a web page saved instead of the file (the Hugging Face “blob” link instead of the “resolve” download link: we reproduced it with a small HTML page F91), a safetensors file F82, a zip, or an image model in the text slot. See Hugging Face downloads.

“model is corrupted or incomplete”

Incomplete downloadF21 · exit code 3
llama_model_load: error loading model: tensor 'output.weight' data is not within the file bounds, model is corrupted or incomplete1
  1. llama_model_load: error loading model: tensor 'output.weight' data is : The file stops early.

Compare the file size with the one on Hugging Face (and the SHA-256 where shown: how to check), then download again.

“unknown model architecture”: your KoboldCpp is older than the model

Unknown architectureF91 · KoboldCpp 1.124.2 · exit code 3
llama_model_load: error loading model: unknown model architecture: 'zzzzz'1gpttype_load_model: error: failed to load model '<path>'Could not load text model: <path>The reported GGUF Arch is: zzzzz2
  1. llama_model_load: error loading model: unknown model architecture: 'zz: The architecture name is the part to read.
  2. The reported GGUF Arch is: zzzzz: Printed on failure only.

We made this message by renaming the architecture in a copy of a working file, so it is the real message for an unknown name, not one seen with a real new model. Users report it for new model families on old versions. To see the architecture before loading, run on the file: it prints general.architecture and exits F91.

Fixes: update KoboldCpp to the latest release (1.124.2, update). If the newest release still lacks it, support follows after the underlying engine adds the model; the rolling pre-release has untested builds with the same file names.

Models split into several files

Names like -00001-of-00003.gguf mean one model in parts. Keep all parts in one folder and load part 1. We tested both ways to get it wrong F97:

Loading part 2 instead of part 1F97 · exit code 3
llama_model_load: error loading model: illegal split file idx: 1 (file: …-00002-of-00003.gguf), model must be loaded with the first split1
  1. llama_model_load: error loading model: illegal split file idx: 1 (file: Load the file ending 00001.
A part is missingF97 · exit code 3
gguf_init_from_file: failed to open GGUF file '…-00003-of-00003.gguf' (No such file or directory)1llama_model_load: error loading model: llama_model_loader: failed to load GGUF split from …-00003-of-00003.gguf
  1. gguf_init_from_file: failed to open GGUF file '…-00003-of-00003.gguf' : Download the missing part into the same folder.

Wrong file type

Safetensors and PyTorch files must be converted to GGUF (how). Formats such as EXL2, GPTQ and AWQ are not GGUF and do not load. Image models go in the Image Gen tab (image generation). We saw a text model in the image slot stop with exit 3 as well.

“missing tensor” or “wrong shape”

Users report these for model variants a build does not support yet (experimental quantizations, new heads) and for broken quantizations. Update, try another quantization from another uploader, or report it upstream. We could not reproduce these without such a file.

Vision projector (mmproj) doesn’t match

Wrong mmprojF89 · exit code 3
mtmd_init_from_file: error: mismatch between text model (n_embd = 896) and mmproj (n_embd = 576)gpttype_load_model: error: failed to load mmproj model!

The projector must come from the same model. See vision.

It starts loading, then runs out of memory

That is a memory problem, not a file problem: see out of memory.

Context size rejected

A value outside 256 to 524288 is rejected before loading with exit code 2 F22. Set a valid value (context size).

Frequently asked questions

Why does KoboldCpp say "failed to load model"?

It is a summary line. The reason is a few lines above it: a missing file, a file that is not GGUF, an incomplete download, an architecture it does not know, or a projector that does not match.

How do I load a model that's split into several GGUF files?

Keep all parts in the same folder and point KoboldCpp at part 1 (name-00001-of-0000N.gguf). We tested it: part 1 loads every part, part 2 alone fails, and a missing part fails with a failed-to-open message.

What does "unknown model architecture" mean?

The model is a kind that your KoboldCpp does not know. Update KoboldCpp. If the newest release still lacks it, support follows after the underlying engine adds it. We reproduced the message by renaming the architecture in a file.

Why does it say invalid or unsupported model file?

The file is not a GGUF. We got the same message from a safetensors file and from a web page saved with a .gguf name, exit code 3.

How do I know my download is complete?

Compare its size with the one on Hugging Face. An incomplete file fails with a message that a tensor's data is not within the file bounds, exit code 3.

Do spaces or foreign letters in the path matter?

Not on Linux or macOS: a path with a space, Cyrillic, ö and ß loaded. On Windows it crashed when the output was redirected to a file, with a charmap encoding error; we did not test a normal console. A plain-English folder name avoids the question.