Error while deserializing header: incomplete metadata, file not fully covered – Minimax H3 HL2VA

快速结论：这个报错通常发生在 SwarmUI 通过 ComfyUI 后端加载 Minimax H3（HL2VA / FL2VA）模型时的 VAE 加载阶段，核心原因是 VAE 权重文件损坏或下载不完整，导致 safetensors 无法解析文件头。优先排查并替换 VAE 文件。

适用环境：Issue 中确认的环境为 SwarmUI + ComfyUI 后端，Linux 系统，模型目录位于 /home/boombaby/Desktop/Comfu/ComfyUI/models/。日志显示存在旧版安装痕迹（过时的 Python 版本、残留的 nunchaku 安装）。Issue 未提供具体的 Python、CUDA、PyTorch、显卡型号版本号，请以自身实际环境为准。

最快修复方案：删除损坏的 VAE 文件及其所在文件夹 SwarmUI/Models/VAE/MiniMaxH3（以及其它 H3 VAE），重启 SwarmUI，让其自动下载有效的 VAE 文件。

注意事项：该方案在 Issue 中由维护者给出为明确处理方法，但提问者反馈“删除并重新下载后仍报同样错误”，说明可能存在其它干扰因素（如旧安装残留、多个后端共用同一损坏文件、缓存未清理等），单靠删除 VAE 不一定能解决。此外，本 Issue 未确认最小可复现的根因，操作前建议备份模型目录。

问题场景

用户在 SwarmUI 中运行 Minimax H3（HL2VA / FL2VA）视频生成工作流，SwarmUI 调用 ComfyUI 后端执行到 VAELoader 节点（Node 11）时失败，前端表现为后端无法加载模型，最终报 “All backends failed to load the model … Cannot generate anything”。相关模型文件为 MiniMax_H3_FL2VA_pruned_nvfp4.safetensors，放置在 ComfyUI/models/diffusion_models/ 目录下。

报错原文

2026-09-11 23:18:07.623 [Debug] [ComfyUI-2/STDERR] [ERROR] !!! Exception during processing !!! Error while deserializing header: incomplete metadata, file not fully covered
...
  File "/home/boombaby/Desktop/Comfu/ComfyUI/nodes.py", line 848, in load_vae
    sd, metadata = comfy.utils.load_torch_file(vae_path, return_metadata=True)
  File "/home/boombaby/Desktop/Comfu/ComfyUI/comfy/utils.py", line 169, in load_torch_file
    with safetensors.safe_open(ckpt, framework="pt", device=device.type) as f:
safetensors_rust.SafetensorError: Error while deserializing header: incomplete metadata, file not fully covered

[Error] [BackendHandler] backend #2 failed to load model with error: ComfyUI execution error (Node 11: VAELoader): Error while deserializing header: incomplete metadata, file not fully covered
[Error] [BackendHandler] Backend request #1 failed: All available backends failed to load the model '/home/boombaby/Desktop/Comfu/ComfyUI/models/diffusion_models/MiniMax_H3_FL2VA_pruned_nvfp4.safetensors'.

原因分析

从 traceback 可以确认，错误发生在 comfy.utils.load_torch_file 使用 safetensors.safe_open 打开 VAE 权重文件时。safetensors 在解析文件头（header）阶段报 incomplete metadata, file not fully covered，这通常意味着文件头部声明的元数据与文件实际字节长度不一致。

可能原因包括：

VAE 文件下载不完整或传输中断，导致文件被截断。
文件在写入或复制过程中损坏，实际大小与元数据记录不匹配。
存在多个 H3 相关 VAE 文件，SwarmUI/ComfyUI 选中了其中一个损坏的文件。
旧安装残留（日志提到过时 Python、nunchaku 等）可能干扰依赖或缓存，但 Issue 未确认这是直接原因。

维护者在评论中直接判断为“corrupt VAE file（VAE 文件损坏）”，这是当前讨论链中最明确的结论。

环境排查

确认 SwarmUI 与 ComfyUI 后端是否为同一套安装，模型目录是否被多个后端共用。
检查 SwarmUI/Models/VAE/MiniMaxH3 目录下是否存在多个 H3 VAE 文件（可能其中一个损坏）。
对比 VAE 与模型文件的文件大小是否与官方发布值一致，排除下载不完整。
核对日志中使用的 Python 版本是否过旧（Issue 提示存在 outdated python version）。
检查是否残留不再需要的 nunchaku 安装（Issue 指出 nunchaku 已不再相关/有效）。
确认显卡与 CUDA/PyTorch 环境与实际模型（nvfp4 量化）要求匹配；Issue 未提供具体版本，无法给出确切对照。

解决步骤

关闭 SwarmUI 及所有相关的 ComfyUI 后端进程，避免运行中锁定文件。
删除损坏的 VAE 目录：SwarmUI/Models/VAE/MiniMaxH3。
同时检查并移除其它 H3 相关 VAE 文件，防止加载到旧的损坏副本。
重启 SwarmUI，等待其自动下载有效的 VAE 文件。
若删除并重新下载后仍报相同错误：检查 ComfyUI/models/diffusion_models/MiniMax_H3_FL2VA_pruned_nvfp4.safetensors 本身是否完整，重新下载该模型文件；并确认没有多个后端/多个安装目录共用同一损坏文件。
可优先尝试：处理旧安装残留（更新过时的 Python、清理不再使用的 nunchaku），或做一次全新安装并迁移 Models、Outputs、Data（设置）。此为维护者针对日志中大量无关错误的建议，并非针对本 VAE 报错的确认修复手段。

验证方法

重启 SwarmUI 后重新运行 Minimax H3 工作流，观察日志中不再出现 Error while deserializing header: incomplete metadata, file not fully covered，且 VAELoader（Node 11）节点不再抛错、后端成功加载模型并开始生成视频。若仍报同样错误，说明问题不止是单一 VAE 文件损坏，需要继续按“环境排查”逐项排除。