Tech

「SafetensorError: Error while deserializing header」の原因と対処

モデル（チェックポイントやLoRA）を読み込もうとすると、こう止まることがある。

safetensors_rust.SafetensorError: Error while deserializing header: HeaderTooLarge

これは、読み込んだファイルが正しいsafetensors形式として壊れている、という意味だ。原因のほとんどは、ファイルの破損かダウンロードの未完了にある。

まずファイルサイズを確認する

本来は数百MBから数GBあるはずのモデルが、数KBしかないことがある。その場合、中身はモデル本体ではなく、ダウンロードに失敗した断片や、Git LFSのポインタファイル、エラーページのHTMLだったりする。

Terminal window
ls -lh model.safetensors

極端に小さいなら、それは本物のモデルではない。

取り直す

ダウンロードが途中で切れた可能性が高い。ブラウザの右クリック保存ではなく、コマンドで取り直すと安定する。

Terminal window
huggingface-cli download <repo> <file> --local-dir ./models

置き場所と拡張子を確認する

拡張子が .safetensors で、ComfyUIやWebUIの正しいフォルダ（checkpoints / loras など）に置かれているかも確認する。

まとめ

  • 原因はファイルの破損かダウンロード未完了
  • まずファイルサイズを見る（小さすぎないか）
  • LFSポインタやHTMLを保存していないか疑う
  • コマンドで取り直す
  • 拡張子と置き場所も確認する