Safetensors のヘッダーエラー：ローダーを変更する前にファイルを検証

症状と対象範囲

.safetensors のヘッダー解析エラーには、ダウンロードの未完了や誤り、異なる形式、パーサーとローダーの不一致が関係している場合があります。エラーメッセージだけでは、破損と断定できません。

検索の手掛かりとなるエラーの断片です。ID、値、ファイル名は環境によって変わります。

HeaderTooLarge
MetadataIncompleteBuffer
Error while deserializing header

出典から確認できること

ComfyUI の公式モデルのトラブルシューティング資料では、ヘッダーエラーを扱っています。Safetensors の仕様では、長さ情報が付いた JSON ヘッダーを定めています。.safetensors という拡張子だけでは、ファイルの内容がその形式に従っているとは確認できません。Hugging Face の資料では、重みデータではなく参照情報である、旧式の Git LFS ポインターファイルについて説明しています。Issue #6928 は再ダウンロードとハッシュ比較を行ったとの報告後も失敗が続いた事例を、Issue #7659 は VAE のメタデータが不完全だった事例を報告しています。これらは調査の手掛かりであり、このサイトがファイルの完全性を検査した結果ではありません。出典 1（英語） 出典 2（英語） 出典 3（英語） 出典 4（英語） Safetensors の形式（英語） LFS ポインター（英語） PowerShell の Get-FileHash（英語）

区別すべき状況

1. 保存された内容が、完全な重みではなく、ログインページやエラーページ、Git LFS ポインター、または途中までのダウンロードである。

2. ファイル自体は完全だが、別の形式やリビジョンのものである。または、誤ったローダーで読み込まれている。

3. 転送、ストレージ、またはパーサーのバージョンに関する問題があり、信頼できる配布元のメタデータとの比較が必要である。

確認手順

以下は引用した資料に基づく編集上の手順です。あなたの環境で原因が確定したことを意味しません。

手順 1. リポジトリ、リビジョン、相対パス、サイズ、取得元を記録します。異常に小さいファイルは調査し、重みファイルをテキストエディターで上書きしないでください。

手順 2. 同じアルゴリズムを使い、対象ファイルと正確に同じリビジョンの上流チェックサムと比較します。信頼できる期待値がない場合は、概算サイズから判断せず、完全性は未確認と記録します。

手順 3. 同じ保存先に同時に書き込むプロセスがない状態で、作者が対応している方法を使って別のファイルにダウンロードします。制限付きリソースの場合は、先にアクセス要件を満たします。

手順 4. 互換性のある最小限のローダー経路を比較します。配布元の正確なハッシュが一致しても解析に失敗する場合は、ファイルの識別情報、パーサーとローダーのバージョン、traceback を記録し、拡張子を繰り返し変更せず、その事例を報告します。ハッシュの一致で確認できるのは、参照先とバイト列が一致することです。パーサーとの互換性は確認できません。

コマンドとリクエスト例

Windows PowerShell では、サンプルのパスを自分のファイルに置き換えます。この読み取り専用コマンドは、お使いのマシンでは実行していません。結果を、対象の上流ファイルと正確に一致する信頼できる期待ハッシュと比較します。ローカルで計算したハッシュだけでは、取得元を証明できません。

Get-FileHash -Algorithm SHA256 -LiteralPath "D:\models\your-model.safetensors"

完了の確認

ファイルの識別情報が取得元と一致し、パーサーが重みを読み込めることを確認します。その後もモデル構造との互換性を検証する必要があります。

制限と注意点

信頼できない pickle／.pt ファイルを読み込んで解析を回避しないでください。このサイトは、ここで言及した大容量の重みファイルをダウンロードしたり、チェックサムを計算したりしていません。

参照した原文資料

• ComfyUI のモデルのトラブルシューティング（英語）（確認日：2026-09-25）
• 報告者がチェックサムを比較した後も HeaderTooLarge が発生した事例（英語）（確認日：2026-09-25、個別の報告）
• VAE の MetadataIncompleteBuffer（英語）（確認日：2026-09-25、個別の報告）
• Hugging Face Hub のダウンロードガイド（英語）（確認日：2026-09-25）
• Safetensors の形式（英語）（確認日：2026-09-25）
• Hugging Face の旧式 Git LFS ポインター（英語）（確認日：2026-09-25）
• PowerShell の Get-FileHash（英語）（確認日：2026-09-25）

出典と英語の表現は 2026-09-25 に再確認しました。このサイトはモデルの重みをダウンロードしたり、ハッシュを計算したり、GPU でテストしたりしていません。修復の保証も示していません。

関連するトラブルシューティング記事とガイド

• Value not in list：ComfyUI の選択肢にモデルが表示されないとき
• Hugging Face の 401／403：ブラウザーでのアクセスとダウンロードプロセスの認可は別
• モデルのダウンロードを記録する：リポジトリ、リビジョン、パス、完全性の証拠