模型加载失败解决：路径、格式与显存排查
排查 ComfyUI model load failed、invalid header、shape mismatch、CUDA out of memory 等模型加载失败错误，按关键词区分路径、文件损坏、家族不匹配和显存不足。
一句话结论
能区分放错目录、文件损坏、版本不匹配和显存不足。
模型排错链路
你现在处在第四步：模型已被发现，但读取或运行失败。完整顺序是：
- 先确认模型家族：SD1.5、SDXL、Flux 或其他体系。
- 再确认文件类型和目录：Checkpoint、LoRA、VAE、ControlNet 不要混放。
- 如果文件不出现在节点下拉框，先去
/guides/model-dropdown-empty/。 - 如果下拉框能选但 Queue 后报错，留在本页按错误关键词分流。
- 模型栈正确后，再调提示词、采样器、CFG 和画质。
完整入口见：/guides/comfyui-model-troubleshooting/。
这篇解决什么问题
模型加载失败通常是路径、文件类型、模型体系或显存问题。先确认“这个文件应该被哪个节点加载”。如果你看到的是红色节点、缺自定义节点，那不是这篇要解决的模型问题，先去看缺节点和导入工作流那两篇。
如果你是第一次接触 ComfyUI，建议不要跳步。先把最小流程跑通，再安装插件、导入复杂工作流或追求高分辨率。ComfyUI 的大多数问题都可以通过“看控制台日志、确认目录、确认版本、降低参数”这四件事定位。
适合谁
- 刚开始使用 ComfyUI，需要一篇可以照着做的教程。
- 已经遇到相关报错，但不知道该先检查哪一步。
- 想把安装、模型、插件、工作流整理成可复查流程的用户。
准备条件
- 知道模型文件名和来源。
- 能查看控制台报错。
模型加载失败先按顺序查：路径是否放对、文件是否完整、显存是否够。不要一上来就重装环境。
上图把最常见的失败分成四类：目录、类型、文件、加载节点。先按这个顺序排，通常比乱重装快得多。
这张图把失败再拆得更细一点：先看目录，再看文件是否损坏，再看 SD1.5 / SDXL / Flux 体系是否匹配，最后才是显存问题。
它在排错链路里的位置
模型加载失败，通常说明文件已经被节点看见了，但在真正读取或运行时失败。也就是说，它排在“模型家族选择”和“下拉框为空”之后：先确认你选的是正确模型家族，再确认模型能出现在对应下拉框，最后才进入本页判断加载失败原因。
| 阶段 | 典型问题 | 下一步 |
|---|---|---|
| 选择模型家族 | 不知道用 SD1.5、SDXL 还是 Flux | 先看 /guides/sd15-vs-sdxl/ |
| 下拉框为空 | 文件没有被对应节点发现 | 先看 /guides/model-dropdown-empty/ 和 /guides/model-file-paths/ |
| 加载失败 | 文件能选，但读取、连接或生成时报错 | 留在本页按报错关键词排查 |
不要把所有失败都叫“模型坏了”。file not found 多半是路径或工作流引用旧文件名；invalid header 多半是文件损坏或下载到 HTML；shape mismatch 多半是 SD1.5 / SDXL / Flux 家族不匹配；CUDA out of memory 则是显存压力，不是模型文件格式错误。
操作步骤
- 确认模型类型：Checkpoint、LoRA、VAE、ControlNet 不同目录。
- 检查文件大小是否正常，几 KB 的 safetensors 通常不是模型本体。
- 确认文件扩展名没有被浏览器改名。
- 看报错是否是 file not found、invalid header、shape mismatch 或 OOM。
- 重新下载可疑模型，优先用官方或可信来源。
- 确认 SD1.5/SDXL 体系匹配。
- 如果提示 invalid header，优先怀疑下载损坏或文件没下完整。
- 如果提示 shape mismatch，先看是不是模型体系不对。
错误关键词索引
先看启动窗口或终端最后 20 行，不要只看网页上的红色提示。不同关键词对应完全不同的处理方式：
| 报错关键词 | 多半原因 | 先做什么 | 不要先做什么 |
|---|---|---|---|
file not found | 工作流引用了作者电脑上的旧文件名，或文件被移动/改名 | 在节点下拉框重新选择本机已有模型，必要时按文件类型补下载 | 不要把无关模型改名伪装成缺失文件 |
No such file or directory | 路径不存在、外部模型路径写错、压缩包没解开 | 回到 models/ 目录和 extra_model_paths.yaml 检查真实路径 | 不要重装 Python 或 CUDA |
invalid header | 下载损坏、下载到 HTML/错误页、文件没下完整 | 看文件大小和来源，删除后重新下载模型本体 | 不要调 CFG、sampler 或提示词 |
pickle data was truncated | 文件未完整下载或复制中断 | 重新下载，避免浏览器/网盘中断 | 不要继续用同一个可疑文件测试 |
shape mismatch | SD1.5 / SDXL / Flux 家族不匹配，或 LoRA/ControlNet 版本不对 | 回到 /guides/sd15-vs-sdxl/ 核对 checkpoint、LoRA、ControlNet 是否同家族 | 不要认为 prompt 能修复模型结构不匹配 |
size mismatch | 模型权重结构和当前节点/加载器预期不一致 | 确认模型类型、基础模型、节点版本 | 不要把 LoRA 当 checkpoint 加载 |
CUDA out of memory | 显存不足、分辨率/batch/ControlNet/upscale 太重 | 降低分辨率、batch、ControlNet 数量或换轻量模型 | 不要反复移动模型目录 |
expected ... channels | VAE、latent、ControlNet 或模型结构连接不匹配 | 检查工作流连接和模型家族，不要只换 checkpoint | 不要只看文件后缀判断兼容 |
如果没有这些关键词，先保存完整 Traceback，再看最后一个报错节点。ComfyUI 的真正原因通常在终端最后几行，而不是页面弹窗标题。
30 秒处理顺序
- 下拉框是否能选到模型？不能选就先回到
/guides/model-dropdown-empty/。 - 终端最后一行是什么关键词？优先按
file not found、invalid header、shape mismatch、CUDA out of memory分流。 - 文件是否明显异常？几 KB 的
.safetensors、.html、.download基本不是可用模型。 - 模型家族是否一致？SD1.5 checkpoint 不要混 SDXL LoRA 或 SDXL ControlNet。
- 如果是 OOM，先降到最小工作流：batch 1、较低分辨率、关闭 upscale、关闭多 ControlNet。
- 如果还是失败，复制完整
Traceback，不要只截网页红框。
这个顺序的目的，是先把“文件能否被读取”和“工作流是否太重”分开。能读取但显存爆，不是文件坏；文件损坏时，降低分辨率也不会解决。
判断问题属于哪一类
- 如果页面打不开，先看启动窗口是否还在运行，以及端口是否正确。
- 如果节点是红色，优先处理缺失自定义节点或插件加载失败。
- 如果模型下拉框为空，优先检查模型类型和放置目录。
- 如果开始生成后失败，优先看显存、模型版本和具体报错节点。
- 如果更新后才坏，优先考虑插件版本不兼容，必要时回退或临时移除插件。
常见错误
- 把网页下载的 HTML 当模型文件。
- LoRA 放 checkpoints 后用 Load Checkpoint 加载。
- 模型未下完就启动。
- 没看清 Base Model 就直接下载。
- 文件后缀像
.safetensors，但内容根本不是模型。
如果还是失败
优先看报错关键词：invalid header、shape mismatch、file not found、CUDA out of memory。这几种不是同一个问题，解决顺序也不一样。只要你先把“目录”和“类型”对齐，后面的判断会快很多。
验证是否成功
- 对应节点能选择模型。
- 加载时控制台无 invalid header。
- 生成阶段不再因模型加载中断。
如果仍然失败
请把控制台里从 Traceback 开始到最后一行的完整报错保存下来，同时记录：ComfyUI 版本、启动方式、显卡型号、显存容量、使用的模型文件名、刚安装过哪些插件。不要只截网页上的红色提示，因为真正有用的信息通常在启动窗口里。
如果你在本站提交反馈，登录状态下会自动附带 user_id，方便后续追踪同一个用户遇到的连续问题；未登录也可以匿名提交。
下一步推荐
- 新手路线：/topics/comfyui-beginner/
- 报错排查：/topics/comfyui-errors/
- 模型基础：/topics/model-basics/
- 插件安装：/topics/must-have-plugins/
更新记录
- 2026-05-12：扩写为正式教程，补充操作步骤、常见错误和验证清单。