加载模型报 Error while deserializing header: HeaderTooLarge（文件根本不是 safetensors）

safetensors_rust.SafetensorError: Error while deserializing header: HeaderTooLarge

现象与触发场景

常见触发场景：

• 用 git clone 拉 Hugging Face 模型仓库但没装 git-lfs（或设了 GIT_LFS_SKIP_SMUDGE=1），拿到的是几百字节的指针文件
• 用浏览器/wget/curl 抓需要登录授权的仓库，存下来的是 HTML 登录页或错误页
• 下载中途被掐断，只下到文件开头一小段

根因

• safetensors 文件格式是「前 8 字节 = 后续 JSON 头的长度（小端 64 位整数）」，库还对头部设了 100MB 上限做防滥用。当文件实际是文本（Git LFS 指针以 version 开头、HTML 以 <!DOCTYPE 或 <html 开头）时，这 8 个字节被当成整数就是一个天文数字，于是报 HeaderTooLarge。
• 所以报错不是「头太大」，而是「压根没有头」——文件不是 safetensors 文件。先量文件大小，再谈重装软件。

解决步骤

已按「最可能有效」排序。请从上往下做，每做完一步用「验证」确认，不要一次改五处。

1. 第一步：量文件大小，别动 Python 环境
   在报错栈里找到它点名的那个文件路径，量一下大小。真实权重是 GB 级；Git LFS 指针一定小于 1024 字节（通常约 130 字节）。同时把文件开头几个字节打印出来：如果能看到可读文本（version / <!DOCTYPE html> / <html），结论就确定了。
   Get-Item .\models\clip\t5xxl_fp8_e4m3fn.safetensors | Select-Object Length
   Get-Content .\models\clip\t5xxl_fp8_e4m3fn.safetensors -TotalCount 3
   ls -lh models/clip/t5xxl_fp8_e4m3fn.safetensors && head -c 200 models/clip/t5xxl_fp8_e4m3fn.safetensors
2. 第二步：按文件类型对症处理（LFS 指针 / HTML 页 / 截断）
   小文件且内容是 version + oid sha256: 三行 → 这是 Git LFS 指针，在克隆目录里执行 git lfs install 再 git lfs pull 让指针被真实对象替换（或干脆别用 git 拉权重，改用 hf CLI）。文件开头是 <!DOCTYPE html> 或 <html → 你下到了登录/错误页，需要带鉴权重新下载：Civitai 用带 token 的 API 下载链接，Hugging Face 受限仓库先用 hf auth login 登录并接受许可协议。文件是二进制但明显比仓库标注的小 → 属于下载被截断，见 MetadataIncompleteBuffer 那条。
   git lfs install
   git lfs pull
   https://civitai.com/api/download/models/<id>?type=Model&format=SafeTensor&token=<YOUR_TOKEN>
   hf auth login
   hf download comfyanonymous/flux_text_encoders t5xxl_fp8_e4m3fn.safetensors --local-dir ./models/text_encoders
3. 第三步：用官方 CLI 重下，避免再次静默失败
   hf CLI（huggingface_hub v0.34 之后取代旧的 huggingface-cli）会做鉴权、校验文件大小、断点续传和重试，失败时会明确报 401 而不是留一个看起来正常的坏文件。国内网络可先设 HF_ENDPOINT 走镜像。
   pip install -U huggingface_hub
   $env:HF_ENDPOINT="https://hf-mirror.com"
   hf download comfyanonymous/flux_text_encoders clip_l.safetensors --local-dir ./models/text_encoders

验证是否修好

补充说明

参考文件大小示例来自 comfyanonymous/flux_text_encoders：clip_l.safetensors 约 246 MB、t5xxl_fp8_e4m3fn.safetensors 约 4.89 GB、t5xxl_fp16.safetensors 约 9.79 GB。新版 ComfyUI 会把该异常包装为「The safetensors file is incomplete. Check the file size and make sure you have copied/downloaded it correctly.」

来源

1. [89] （社区）　Safetensors HeaderTooLarge Error? Your Model File Isn't a Model — the 　https://runaihome.com/blog/safetensors-headertoolarge-error-fix-2026/
2. [90] （官方 issue）　CLIPVisionLoader Error while deserializing header: HeaderTooLarge · Is　https://github.com/Comfy-Org/ComfyUI/issues/5797
3. [91] （节点仓库 issue）　safetensors_rust.SafetensorError: Error while deserializing header: He　https://github.com/diontimmer/ComfyUI-Vextra-Nodes/issues/17
4. [92] （官方 issue）　Header too large error · Issue #7510 · Comfy-Org/ComfyUI　https://github.com/Comfy-Org/ComfyUI/issues/7510

这条报错里提到的模型文件

下面这些文件名出现在本条报错的原文或解决步骤里（与权重库的文件名精确匹配），站内权重库有对应条目。 要哪个就按「放哪个目录」放好，文件名一字不差（含大小写与扩展名）。

本条报错提到的目录

本条报错的原文或解决步骤里出现了下面这些 models/ 子目录。 权重库里放在这些目录下的文件已按目录列好，可对照确认自己缺的是哪几个。

这条报错要用到的东西

按本条报错所属的类别（模型与权重文件加载）列出站内相关的下载包与板块入口。 它们不是「必须下载才能修好」，而是这一类问题里最常要动到的东西；具体怎么做，以上面的解决步骤为准。

同一类别的其他条目

返回报错库