GGUFモデルが読み込めない原因と対処法｜エラー別

先に結論

GGUFが読み込めないときは、ファイル本体 → llama.cppの版 → 分割ファイルやmmproj → メモリ／GPUの順に切り分けると、無関係な設定変更を減らせます。
invalid magicはGGUFではないファイルや不完全なダウンロード、unknown model architectureは古い実行ファイルまたは未対応構造、missing tensorは不完全な変換・版の不一致・破損をまず疑います。
failed to load modelは最終結果にすぎません。原因は、その直前に出た最初の具体的なエラーから判断します。
ファイルを再変換したりメタデータを上書きしたりする前に、版、先頭4 byte、配布元の容量、全shard、CPU限定起動を確認してください。

対象: llama.cppのllama-cliまたはllama-serverで、手元のGGUFをロードできない人。

確認日時: 2026年8月2日 14:00（Asia/Tokyo）
固定した版: llama.cpp master HEAD 11924d4c17abc27383376a1ac6a24fa3e36c1c0c、GGUF仕様 78de606907c364b76601f734021f76bd29ca5637
検証区分: 公式仕様、README、loader実装を照合した机上調査です。特定のGGUFを破損させる試験や、各GPUでの実機ロードは行っていません。エラー文はbuildやwrapperにより前後します。
画像: アイキャッチはGGUFの診断工程を表した当サイトの要点図解で、実際のエラー画面ではありません。

最初に保存する4つの情報

再ダウンロードや再ビルドの前に、再現条件を残します。次の例はBash／Zsh向けです。MODEL_GGUFを実ファイルの絶対パスへ置き換えてください。

MODEL_GGUF="/absolute/path/to/model.gguf"

command -v llama-cli
llama-cli --version
ls -lh "$MODEL_GGUF"
llama-cli -m "$MODEL_GGUF" -c 2048 -n 1 -st -p "test" 2>&1 | tee llama-load.log

残すのは、実行ファイルの場所、--versionの出力、GGUFのファイル名と容量、エラーを含む起動ログです。複数のllama.cppを入れている環境では、更新したソースと実際に呼ばれたバイナリが別ということがあります。Python wrapper、GUI、Dockerを使う場合も、その内側のllama.cpp版を記録します。

ログは末尾のfailed to load modelだけでなく、最初に現れたinvalid magic、unknown model architecture、missing tensor、failed to allocateなどを探します。

エラー別の原因早見表

ログの手掛かり	最初に疑うこと	最初の対応
`invalid magic`	GGUFではない、HTMLやGit LFS pointer、不完全な取得	先頭4 byteと配布元の容量を確認
`failed to load model from ...`	総括メッセージで原因は複数	直前の具体的なエラーまで遡る
`unknown model architecture`	loaderが古い、または対象構造が未対応	実際に使うバイナリ／wrapperを更新
`missing tensor`	converterとloaderの版差、不完全な変換・配布	配布元と版を確認し、正規ファイルを再取得
`failed to load GGUF split`	shard不足、名前変更、別directory	全shardを同じdirectoryへ置く
`model must be loaded with the first split`	2番目以降のshardを指定	`00001-of-XXXXX`を指定
`failed to allocate`、OOM	RAM／VRAM、context、GPU offload	CPU限定・短いcontextで切り分け
`mmproj`、`clip`周辺	projectorを本体として指定、組み合わせ違い	言語モデルと対応mmprojを分けて指定
`unknown argument`	モデルではなくCLIの版差	手元の`--help`へオプションを照合

この表で候補を絞り、以下を上から順に確認します。

1. GGUF本体とダウンロードを確認する

先頭4 byteが`GGUF`か確認する

GGUF仕様では、ファイル先頭のmagic numberはbyte列で47 47 55 46、ASCIIではGGUFです。拡張子を.ggufへ変更しただけではGGUFになりません。

MODEL_GGUF="/absolute/path/to/model.gguf"

od -An -tx1 -N4 "$MODEL_GGUF"

期待する表示は次です。

47 47 55 46

異なる場合は、モデルページではなくHTMLを保存した、redirectを追わずに取得した、Git LFSのpointerだけを取得した、旧GGML形式をGGUFとして指定した、またはダウンロードが途中で終わった可能性があります。拡張子の変更やmetadataの強制上書きでは直りません。公式・信頼できる配布元から取得し直します。

容量とhashは「比較対象」があって初めて役立つ

配布ページに表示されたファイル容量と手元の容量を照合します。配布者がSHA-256を公開している場合は、同じalgorithmで照合します。

# Linux
sha256sum "$MODEL_GGUF"

# macOS
shasum -a 256 "$MODEL_GGUF"

自分で計算したhashだけでは、正しいファイルかは判定できません。公開されたhashまたは以前に保存したmanifestとの一致が必要です。llama.cppにはtensor単位も扱えるllama-gguf-hashがありますが、これも比較元がなければ現在のファイルの指紋を作るだけです。

`--check-tensors`は追加検査であり、配布元との同一性証明ではない

現行のllama-cliにはtensor dataのinvalid valueを調べる--check-tensorsがあります。

llama-cli \
  -m "$MODEL_GGUF" \
  --check-tensors \
  -dev none \
  -c 2048 \
  -n 1 \
  -st \
  -p "test"

検査には時間がかかる場合があります。また、通過しても配布者の元ファイルとbyte単位で同じことを証明するものではありません。magic、容量、公開hash、loader検査を組み合わせます。

2. llama.cppとwrapperの版を揃える

GGUFは拡張可能な形式ですが、新しいモデル構造を実行するにはloader側の実装も必要です。unknown model architecture: '...'が出た場合、GGUFにgeneral.architectureがあっても、手元のllama.cppがその値へ対応していなければロードできません。現行loaderが未知のarchitectureを例外にすることは公式ソースでも確認できます。

対応は次の順です。

配布元model cardで推奨するllama.cpp版やreleaseを確認する
command -v llama-cliとllama-cli --versionで実行物を特定する
llama.cpp本体、package、Python binding、GUI、Docker imageのうち、実際にloaderを含むものを更新する
更新後にもう一度--versionを保存する

--override-kv general.architecture=...で別architectureを装う方法は解決になりません。必要なtensor構造や演算実装が追加されるわけではなく、別のエラーや誤動作へ進むおそれがあります。

missing tensor '...'は単純な物理破損だけでなく、converterが新しいtensor省略規則で書き、loaderが古い場合にも起こり得ます。自作GGUFなら、converterと実行側を同じllama.cpp commitへ揃えて再変換します。第三者配布GGUFなら、作者のmodel cardとissueを確認し、勝手にtensor名を変えず正しい成果物を再取得します。

3. 分割GGUFは全shardを同じ場所へ置く

分割モデルは、一般に末尾が00001-of-00005.ggufのようになります。GGUF命名仕様ではshard番号は1始まりの5桁です。現行loaderは最初のsplitからsplit.countを読み、後続ファイルを探索し、件数、index、tensor総数を検査します。

Model-Q4_K_M-00001-of-00003.gguf
Model-Q4_K_M-00002-of-00003.gguf
Model-Q4_K_M-00003-of-00003.gguf

確認点は次の4つです。

全shardを同じdirectoryへ置いたか
of-00003に対して1〜3がすべてあるか
配布時のbase nameや番号を変更していないか
-mには1番目のshardを指定したか

llama.cppのmodel loaderは、最初のsplit以外からの開始、split数の不一致、後続GGUFの読み込み失敗、tensor数の不一致を別々に検出します。まとめたい場合は公式のllama-gguf-split —mergeを使えますが、merge前に十分な空き容量と出力先を確認してください。通常のロードだけならmergeは必須ではありません。

4. VLMでは本体GGUFとmmprojを混同しない

画像入力対応モデルでは、言語モデル本体とmultimodal projectorが別GGUFで配布される場合があります。mmproj-...ggufを-mの言語モデルとして渡すと、projectorのarchitectureを通常LLMとしてロードしようとして失敗します。

ローカルファイルを使う基本形は次です。

MODEL_GGUF="/absolute/path/to/language-model.gguf"
MMPROJ_GGUF="/absolute/path/to/mmproj-model.gguf"
IMAGE_FILE="/absolute/path/to/image.jpg"

llama-cli \
  -m "$MODEL_GGUF" \
  --mmproj "$MMPROJ_GGUF" \
  --image "$IMAGE_FILE" \
  -ngl auto \
  -c 4096 \
  -cnv

言語モデルとmmprojは、同じmodel family、規模、版に対応する組を選びます。現行の公式multimodal資料でも、通常は2つのGGUFを使う構成が説明されています。Hugging Faceから-hfで取得する場合は、利用可能なmmprojを自動取得する現行機能もあります。詳しい実行例はllama.cppのコマンド例を参照してください。

5. CPU限定・短いcontextでメモリ問題を分離する

magic、容量、版、shardが正しく、ログにallocationやGPU backendのエラーが出る場合は、ファイル破損と決めつけずメモリ経路を切り分けます。

llama-cli \
  -m "$MODEL_GGUF" \
  -dev none \
  -c 2048 \
  -n 1 \
  -st \
  -p "test"

これはGPU offloadを無効にしますが、モデルを置けるsystem RAMは必要です。結果は次のように読みます。

CPU限定でロードできる: GGUF本体は読める可能性が高く、GPU backend、VRAM、offload設定を重点確認
CPU限定でも同じmetadata／tensorエラー: ファイル、モデル対応、loader版を重点確認
CPU限定でもallocation失敗: system RAM、swap、他process、モデル規模を確認

GPU側の必要容量は「GGUFのファイルサイズ」だけではありません。重み、KV cacheを含むcontext、compute buffer、他processの使用量が加わります。ローカルLLMに必要なVRAMの計算方法で見積もってから、contextを短くする、より小さい量子化を選ぶ、GPU offloadを減らす順で調整します。ロード後の生成が遅い場合はllama.cppが遅い原因と高速化設定へ進んでください。

最短の診断フロー

起動ログ全体とllama-cli --versionを保存する
od -An -tx1 -N4で47 47 55 46を確認する
配布ページの容量と、公開されていればhashを照合する
unknown architectureなら実際に使われるloaderを更新する
分割モデルなら1番目から全shardを同じdirectoryへ置く
VLMなら言語モデルと対応mmprojを分ける
-dev none -c 2048でGPU経路を外して再現する
それでも失敗する場合は、完全なログ、版、model card、OS、backend、メモリ容量を添えて配布元またはllama.cppへ報告する

初めてGGUFを動かす段階なら、先にllama.cppでGGUFモデルを動かす方法で正常系の最小コマンドを確認すると、手順差を見つけやすくなります。GUI中心で使うか細かく切り分けるか迷う場合はOllamaとllama.cppの用途別比較も参考にしてください。

よくある質問

拡張子が`.gguf`ならGGUFですか？

いいえ。拡張子は名前にすぎません。先頭magic、容量、配布元、必要ならhashを確認してください。

最新版llama.cppへ更新すれば必ず読めますか？

必ずではありません。新しいarchitectureがまだ未実装、GGUF自体が不完全、wrapperが古い内部buildを使う、必要なmmprojやshardが欠ける場合があります。モデル配布元が指定する対応版を優先します。

`--check-tensors`が通れば破損していませんか？

invalid valueの追加検査にはなりますが、配布元との完全一致を単独で証明しません。公開hashやmanifestがあるなら照合してください。

OOMはGGUFの破損ですか？

通常は容量やallocation経路の問題です。短いcontext、CPU限定、少ないGPU offloadで分離し、重み以外のcontext・compute bufferも含めて見積もります。

GGUFを自分で修復できますか？

欠けたbyteやtensorを推測して安全に復元することはできません。正しい元ファイルの再取得、全shardの回収、同じcommitのconverterによる再変換が基本です。

まとめ

GGUFのロード失敗は、1つの原因に見えても「ファイル」「loader版」「付属ファイル」「メモリ」の4層に分かれます。最初にログと版を保存し、magicと容量を確認してから、architecture、shard、mmproj、CPU限定起動へ進むと診断がぶれません。

特に避けたいのは、総括メッセージだけを見て再変換を始めることと、未知のarchitectureをmetadata上書きで別物に見せることです。直前の具体的エラーを基準に、正しい成果物と対応loaderを揃えてください。

参考資料

ggml：GGUF仕様（commit 2026年7月31日、確認日 2026年8月2日）
llama.cpp：model loader実装（commit 2026年8月2日・日本時間）
llama.cpp：llama-cli引数表（commit 2026年8月2日・日本時間）
llama.cpp：GGUF split／merge（commit 2026年8月2日・日本時間）
llama.cpp：GGUF hash utility（commit 2026年8月2日・日本時間）
Hugging Face Hub：GGUF（確認日 2026年8月2日）