Skip to content

Commit 48319de

Browse files
authored
docs: add FAQ entry for "unknown model architecture" error
summary: Adds a missing FAQ entry covering the "error loading model architecture: unknown model architecture: 'X'" error, which is one of the most commonly reported issues but currently has no dedicated entry in the docs FAQ. changes: - Added a new FAQ entry to `docs/FAQ.md` explaining the cause, and three solutions in order of preference (update LLamaSharp, check model date, compile llama.cpp yourself) - Includes a caution note about self-compiled backends
1 parent b5fc51c commit 48319de

1 file changed

Lines changed: 23 additions & 0 deletions

File tree

docs/FAQ.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,26 @@ In this inequality, `len(response)` refers to the expected tokens for LLM to gen
6262
## Choose models weight depending on your task
6363

6464
The differences between modes may lead to much different behaviours under the same task. For example, if you're building a chat bot with non-English, a fine-tuned model specially for the language you want to use will have huge effect on the performance.
65+
66+
## Why am I getting "error loading model architecture: unknown model architecture: 'X'"?
67+
68+
This error means the model's architecture is not supported by the version of
69+
llama.cpp that the current LLamaSharp backend is built against.
70+
71+
The most common cause is using a model that was released after your installed
72+
version of LLamaSharp. Newer model families (e.g. Gemma, Qwen)
73+
require a backend built against a newer llama.cpp commit.
74+
75+
**Solutions, in order of preference:**
76+
77+
1. **Update LLamaSharp** to the latest version and reinstall the matching backend
78+
package. Check the version table at the bottom of the README to confirm which
79+
model families are verified for each release.
80+
81+
2. **Check the model's publishing date** on Hugging Face. If it predates your
82+
LLamaSharp version, the architecture may not yet be supported - open an issue
83+
on the repository to request support.
84+
85+
3. **Compile the compatible llama.cpp build yourself**, then point LLamaSharp to it with NativeLibraryConfig.All.WithLibrary()
86+
87+
> **Caution:** Using a self-compiled library that does not match the LLamaSharp version's expected commit is unsupported and may cause crashes or unexpected behaviour. Only do this as a last resort.

0 commit comments

Comments
 (0)