知仓学习社知仓学习社
加载模型报 MetadataIncompleteBuffer 或 incomplete metadata：文件下载被截断 / 全站资源搜索
搜索 更新 2026-10-02
报错 035 模型与权重文件加载 有来源可查

加载模型报 MetadataIncompleteBuffer 或 incomplete metadata：文件下载被截断

报错原文（原样） 
safetensors_rust.SafetensorError: Error while deserializing header: MetadataIncompleteBuffer
...
safetensors_rust.SafetensorError: Error while deserializing header: incomplete metadata, file not fully covered
检索关键词 MetadataIncompleteBuffer、incomplete metadata, file not fully covered、Error while deserializing header、safetensors_rust.SafetensorError、load_torch_file
先看这一句 上一次还能用的模型突然加载失败；报错出现在 CheckpointLoaderSimple、VAELoader、CLIPLoader 或自定义节点的模型加载环节，提示元数据不完整或文件未被完全覆盖。
适用版本 全版本通用（与 ComfyUI 版本无关，取决于文件本身） · 核实日期 2026-09-26 · 状态 已核实
适用环境：Windows 便携版、秋叶/绘世整合包、ComfyUI Desktop、Linux + 云 GPU、Docker/服务器、全部主流环境

现象与触发场景

常见触发场景：

  • 下载到 90% 左右网络中断、浏览器标签被提前关掉、磁盘写满
  • 用不支持断点续传的工具下载大文件，续传后拼出的文件长度不对
  • 在云端/容器里上传大文件时被 CDN 或代理截断

根因

  • safetensors 的头部 JSON 记录了每个张量的偏移与长度。文件被截断时头部本身可能仍然能解析，但头部承诺的数据区没有全部落盘，于是库检测到「文件未被完全覆盖」而失败。
  • 与 HeaderTooLarge 的区别很关键：HeaderTooLarge 说明开头根本不是二进制权重（指针/HTML），MetadataIncompleteBuffer 说明开头是真权重但没下完。
  • 截断的量级有时很隐蔽：应为 4.89 GB 的文件只有 4.7 GB，肉眼扫一眼文件夹根本看不出来。

解决步骤

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

  1. 第一步：比对文件大小与仓库标注值
    打开该模型在 Hugging Face / Civitai 的 Files 页，逐个核对字节数。差一点点也算不合格——不要靠「看起来差不多」放过它。官方文档给出的排查顺序就是：重新下载模型（下载过程中文件可能已损坏）→ 检查磁盘剩余空间（模型可能 2-15GB+）→ 检查文件读取权限 → 换一个模型测试以区分是模型问题还是系统问题。
    Get-ChildItem .\models\checkpoints | Select-Object Name, Length
    df -h /
    Get-PSDrive -PSProvider FileSystem
  2. 第二步：用哈希校验确认完整性（不能只靠大小）
    Hugging Face 每个 LFS 文件都公开 SHA-256（在仓库页面点开该文件，oid 即为哈希）。本地算一遍 SHA-256 与之比对；不一致就是下载坏了，必须重下。文件很大的话这条命令会跑一会儿，属于正常。
    Get-FileHash .\models\checkpoints\model.safetensors -Algorithm SHA256
    sha256sum models/checkpoints/model.safetensors
  3. 第三步：用可断点续传且会报错的工具重下
    hf download 支持断点续传：同一条命令重跑会从断点继续而不是从头开始，这正是修复截断下载的关键；它还会校验大小并在鉴权失败时明确报 401。下完后按正确模型类型放进 models/checkpoints、models/vae、models/text_encoders 等对应目录。
    hf download <repo_id> <filename> --local-dir ./models/checkpoints
    hf download Kijai/WanVideo_comfy <filename> --local-dir ./models/diffusion_models

验证是否修好

重新加载模型不再报错；本地 SHA-256 与仓库标注值完全一致；同一工作流能完整跑完并出图。

补充说明

官方文档在「模型加载错误」一节把 “Error while deserializing header” 的第一条处理办法直接写为「重新下载模型 - 下载过程中文件可能已损坏」。另有社区案例显示 SeedVR2 等节点也会抛同一条 incomplete metadata 报错。

来源

按可信度排列：官方 issue / 官方文档 > 节点仓库 issue > 社区帖 > 中文社区文章。 链接以纯文本给出（本站不做站外跳转），需要核对时请自行复制到浏览器打开。
  1. [93] （官方文档）　如何排查和解决 ComfyUI 中模型相关的问题 - ComfyUI 官方文档　https://docs.comfy.org/zh/troubleshooting/model-issues
  2. [94] （官方文档）　Error while deserializing header: incomplete metadata, file not fully 　https://forum.comfy.org/t/error-while-deserializing-header-incomplete-metadata-file-not-fully-covered/3797
  3. [95] （节点仓库 issue）　safetensors_rust.SafetensorError: Error while deserializing header: Me　https://github.com/kijai/ComfyUI-CogVideoXWrapper/issues/99
  4. [96] （官方 issue）　FlashVsr. LoadWanVideoT5TextEncoder Error while deserializing header: 　https://github.com/Comfy-Org/ComfyUI/issues/10675

本条报错提到的目录

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

models/diffusion_models/权重库里有 57 个文件放在这个目录 看这一目录 models/text_encoders/权重库里有 34 个文件放在这个目录 看这一目录 models/vae/权重库里有 23 个文件放在这个目录 看这一目录 models/checkpoints/权重库里有 11 个文件放在这个目录 看这一目录

这条报错要用到的东西

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

ComfyUI 权重库（167 个文件 / 约 1187 GB）按 ComfyUI 的 models 目录分好类的 167 个权重文件 / 每个文件一份说明（放哪、被哪些工作流引用） 待挂载
权重库每个文件放哪个目录、文件名怎么写、被哪些工作流引用 板块 模型档案按上游仓库看完整文件树与体积 板块

同一类别的其他条目

【034】加载模型报 Error while deserializing header: HeaderTooLarge（文件根本不是 safetensors） 有来源 【036】下拉框里找不到模型 / 报 Value not in list: ckpt_name not in []（模型放错目录或没刷新） 有来源 【037】LoRA 加载报 lora key not loaded：LoRA 与底模架构不匹配或被当成 checkpoint 加载 有来源 【038】IPAdapter 报 ClipVision model not found：CLIP Vision 是独立文件，需放进 models/clip_vision 有来源 【039】GGUF 量化模型加载失败：节点缺失、放错目录、与 fp8 混用 有来源
这个解法对你有效吗 记录只存在你自己的浏览器里，不需要注册账号。

返回报错库