# error: failed to load model: incompatible GGUF version: model version is 3, but llama.cpp supports version 2

- **ID:** `llm/llamacpp-gguf-version-mismatch`
- **Domain:** llm
- **Category:** install_error
- **Verification:** ai_generated
- **Fix Rate:** 95%

## Root Cause

GGUF model file was created with a newer version of the GGUF format (e.g., v3) than what the installed llama.cpp build supports (e.g., v2), due to outdated llama.cpp binaries.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| llama.cpp 2023-10-01 | active | — | — |
| llama.cpp 2023-12-15 | active | — | — |
| llama.cpp 2024-01-10 | active | — | — |
| GGUF v2 | active | — | — |
| GGUF v3 | active | — | — |

## Workarounds

1. **Update llama.cpp to the latest version by rebuilding from source:

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make clean && make -j
./main -m model.gguf** (95% success)
   ```
   Update llama.cpp to the latest version by rebuilding from source:

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make clean && make -j
./main -m model.gguf
   ```
2. **Use a pre-built binary from the latest release on GitHub:

wget https://github.com/ggerganov/llama.cpp/releases/latest/download/llama.cpp-main-ubuntu-x64.tar.gz
tar -xzf llama.cpp-main-ubuntu-x64.tar.gz
./main -m model.gguf** (90% success)
   ```
   Use a pre-built binary from the latest release on GitHub:

wget https://github.com/ggerganov/llama.cpp/releases/latest/download/llama.cpp-main-ubuntu-x64.tar.gz
tar -xzf llama.cpp-main-ubuntu-x64.tar.gz
./main -m model.gguf
   ```

## Dead Ends

- **** — Downgrading may lose metadata or quantization information; converters often produce corrupted files when going backward. (60% fail)
- **** — Breaks file integrity checks and causes undefined behavior or crashes during model loading. (90% fail)