ComfyUI 报错速查表：18 个高频报错的原文、原因与解决步骤

ComfyUI 的报错有一个共同点：真正的线索在最后一行和第一行。最后一行是异常类型与消息，第一行往往指出是哪个文件、哪个节点出的问题。排查前先做三件事：把控制台滚到出错处完整读一遍（界面上的弹窗可以点「Show report / 显示报告」查看完整堆栈）；确认是核心问题还是插件问题；一次只改一个变量再复现。下面 18 条按同样格式给出「报错原文片段 / 原因 / 解决步骤」，报错文案会随版本变化，请以你屏幕上的实际输出为准。

一、启动与运行类

1. CUDA out of memory（显存不足）

报错原文片段：torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate 512.00 MiB. GPU 0 has a total capacity of 11.99 GiB of which 1.23 GiB is free.

原因：当前分辨率、批量或模型规模超过了显卡实际可用显存；也可能只是别的程序占着显存。

解决步骤：

1. 执行 nvidia-smi，看 Memory-Usage 一列，确认没有浏览器、游戏、录屏软件在占显存。
2. 把分辨率降到模型的基础档（SD1.5 用 512 档，SDXL / Flux 用 1024 档），batch_size 先设为 1。
3. 卸掉工作流里没用到的 LoRA、ControlNet、放大节点。
4. 启动加 --lowvram，仍报错加 --novram。
5. 仍不够就降精度（UNet fp8）或改用 tiled 解码——完整策略与参数见显存与速度调优。

2. Torch not compiled with CUDA enabled

报错原文片段：AssertionError: Torch not compiled with CUDA enabled

原因：当前环境里装的是 CPU 版 PyTorch。手动安装时最常出现在未指定 CUDA 索引直接 pip install torch 之后。

解决步骤：

# 1) 先确认当前状态
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

# 2) 卸掉 CPU 版，按官方命令重装（N 卡；老卡把 cu130 换成 cu126）
pip uninstall -y torch torchvision torchaudio
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

便携版出现同样报错说明内置环境被破坏，最稳妥的做法是重新解压一份便携包，或在 python_embeded 里执行上面的重装命令。

3. No module named ‘xformers’（或其它缺失模块）

报错原文片段：ModuleNotFoundError: No module named 'xformers'（同形态还有 No module named 'insightface'、'onnxruntime' 等）

原因：某个自定义节点声明了额外依赖，而你的环境里没装。新版 ComfyUI 核心已经不依赖 xformers，这类报错几乎都来自插件。

解决步骤：

1. 先判断这个插件你是否真的需要。不需要就在设置里禁用它，或把 custom_nodes 下对应目录移出。
2. 需要的话，用「ComfyUI 正在使用的那个 Python」装包。便携版：

   cd /d D:\AI\ComfyUI_windows_portable
   .\python_embeded\python.exe -m pip install 缺少的包名 -i https://pypi.tuna.tsinghua.edu.cn/simple

   源码 + venv 安装：先 venv\Scripts\activate，再 pip install 缺少的包名。

3. 注意 xformers / flash-attention 这类包对 PyTorch 与显卡架构有版本要求，装错版本会导致启动直接崩；不确定就先不装。
4. 装完必须完全重启 ComfyUI（关掉命令行窗口重新双击启动脚本）。

4. Missing Node Types（缺少自定义节点）

报错原文片段：界面弹窗 Missing Node Types；控制台或提交任务时看到 Node '33' has no class_type. The workflow may be corrupted or a custom node is missing.；缺失节点在画布上显示为红色。

原因：打开的工作流用了你本机没安装的插件节点（多数来自他人分享的工作流）。

解决步骤：

1. 优先用 ComfyUI-Manager 在线安装：新版核心可通过启动参数 --enable-manager 启用，界面里打开 Manager → 缺失节点 → 安装，装完按提示重启。
2. 手动安装：在节点名/GitHub 找到对应仓库，克隆到 custom_nodes 下，再装它的依赖：

   cd /d D:\AI\ComfyUI_windows_portable\ComfyUI\custom_nodes
   git clone 插件仓库地址
   cd 插件目录 && ..\..\..\python_embeded\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 插件来源不明时不要装。缺节点不影响你用模板走通基础流程，先把核心功能跑顺更重要。
4. 装完仍显示红色：重启程序 + Ctrl + F5 强刷浏览器。

5. 所有插件同时失效 / 启动即崩（IMPORT FAILED）

报错原文片段：启动日志里逐个插件打印 IMPORT FAILED，或某一行报 Cannot import ... custom_nodes 后进程退出。

原因：插件之间依赖冲突、某个插件不兼容当前版本，或插件目录里残留了半成品文件。

解决步骤：官方推荐的做法是先整体禁用再二分定位：

# 便携版：编辑 run_nvidia_gpu.bat，在参数末尾加上
--disable-all-custom-nodes

# 源码 + venv
python main.py --disable-all-custom-nodes

能正常启动说明问题出在插件：把 custom_nodes 下目录分成两半，逐半启用（或逐半移出目录），直到锁定那个插件，再决定更新、替换还是删除。若禁用全部插件仍崩溃，问题在核心环境，看第 2、13 条。

二、模型与文件类

6. checkpoint 加载报错 / 文件损坏

报错原文片段：ERROR: Could not detect model type of: D:\...\models\checkpoints\xxx.safetensors

原因：文件不是模型权重（例如把 LoRA 或 VAE 放进了 checkpoints）、下载不完整、格式/版本不被当前 ComfyUI 支持。

解决步骤：

1. 核对文件体积：与模型页标注的大小对比，明显偏小说明没下完。
2. 确认类型：LoRA 应放 models\loras，VAE 放 models\vae，单 UNet 放 models\diffusion_models 或 models\unet。
3. 用哈希校验：模型页一般给出 SHA256 或 AutoV2，本地用 PowerShell 计算后比对：

   Get-FileHash -Algorithm SHA256 "D:\AI\ComfyUI_windows_portable\ComfyUI\models\checkpoints\xxx.safetensors"

4. 哈希对不上就删掉重下；反复失败换渠道下载后重新校验。

7. 模型放进去了，加载器列表还是空的

报错原文片段：下拉菜单只有 None；强行运行时提示 Value not in list。

原因：文件放错了 models 子目录，或放对之后没有重启程序。

解决步骤：

1. 对照工作流与模型管理的目录表逐个核对（checkpoints / loras / vae / controlnet / clip 等）。
2. 完整重启 ComfyUI（刷新浏览器有时能看到新节点，但模型列表以重启后为准）。
3. 想让模型放在别处，用根目录下的 extra_model_paths.yaml（由 extra_model_paths.yaml.example 复制改名），改完重启。
4. 确认磁盘权限正常：不要放在需要管理员权限的目录、不要用中文路径。

8. safetensors 文件不完整（下载中断）

报错原文片段：safetensors_rust.SafetensorError: Error while deserializing header: ...，常见附言类似 incomplete metadata, file not fully covered，或 HeaderTooLarge。

原因：下载中途断开、被代理截断，或把浏览器临时文件（.part / .crdownload）改名成了 .safetensors。

解决步骤：

1. 确认目录里没有 .part、.tmp 这类残留文件冒充模型。
2. 重新下载，优先选择支持断点续传的工具；下载时不要改名、不要中途换目录。
3. 下完先看体积是否与模型页一致，再按第 6 条做哈希校验。

三、环境与网络类

9. 端口 8188 被占用，启动失败

报错原文片段：OSError: [Errno 10048] error while attempting to bind on address ('127.0.0.1', 8188)；中文系统上可能显示「每个套接字地址（协议/网络地址/端口）只允许使用一次」。

原因：上一次的 ComfyUI 进程没有退出干净，或 8188 被其他程序占用。

解决步骤：

1. 先看桌面：是不是已经有一个 ComfyUI 窗口在运行，直接用它即可。
2. 换端口启动（官方参数 --port，默认 8188），例如 --port 8189，然后访问 http://127.0.0.1:8189。
3. 想找出占用者：

   netstat -ano | findstr :8188
   tasklist /FI "PID eq 上一步查到的PID"

   确认是残留的 Python 进程后，用任务管理器结束它，或 taskkill /PID 进程号 /F。

10. pip 安装超时 / 卡在下载

报错原文片段：ReadTimeoutError: HTTPSConnectionPool(host='pypi.org', port=443): Read timed out.，或长时间刷 WARNING: Retrying (Retry(total=...))

原因：直连官方源在部分网络环境下不稳定。

解决步骤：

# 单次安装换国内镜像并加大超时
pip install 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 120

# 写成长期配置（换源后所有包默认走镜像）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.timeout 120

注意例外：安装 torch / torchvision / torchaudio 时请用 PyTorch 官方索引（--extra-index-url https://download.pytorch.org/whl/cu130），不要用国内 PyPI 镜像，否则可能装到不带 CUDA 的版本，直接跳到第 2 条。阿里云镜像 https://mirrors.aliyun.com/pypi/simple/ 可作为备用。

11. 升级 ComfyUI 后启动报缺少前端/依赖包

报错原文片段：ModuleNotFoundError: No module named 'comfyui_frontend_package'（或 comfyui_workflow_templates 之类的包）

原因：拉取了新代码（git pull / 更新脚本）但没有同步安装新增依赖。

解决步骤：在 ComfyUI 目录下重新安装依赖，然后重启：

# 源码 + venv
venv\Scripts\activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 便携版
.\python_embeded\python.exe -m pip install -r ComfyUI\requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

12. torch 与 CUDA / 显卡架构不匹配

报错原文片段：三种典型形态——CUDA error: no kernel image is available for execution on the device；RuntimeError: Detected that PyTorch and torchvision were compiled with different CUDA major versions；或日志里出现驱动版本过旧的警告。

原因：显卡架构太老（例如 10 系 Pascal）而装了新版 PyTorch 构建；或 torch 与 torchvision 版本不成套；或驱动版本低于该 CUDA 构建的最低要求。

解决步骤：

1. 先看清基础信息：nvidia-smi（驱动支持的 CUDA 版本）+ python -c "import torch; print(torch.__version__, torch.version.cuda)"。
2. 驱动过旧：去 NVIDIA 官网更新驱动，重启后再复现。
3. 老卡（10 系及更早）：改用 CUDA 12.6 构建，甚至便携版的 _cu126 包：

   pip uninstall -y torch torchvision torchaudio
   pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu126

4. torch 与 torchvision 版本不匹配：三个包在同一条命令里一起重装，不要单独升级其中一个。

13. 显存碎片导致的随机 OOM

报错原文片段：CUDA out of memory. Tried to allocate 20.00 MiB，但 nvidia-smi 显示仍有几 GB 空闲；同一工作流时好时坏。

原因：反复切换模型、批量任务交替执行后，显存被切成不连续的小块，「总量够、连不起来」。

解决步骤：

1. 启动参数加 --disable-smart-memory（更主动地把模型卸回内存），并给系统保留余量：--reserve-vram 1。
2. 减少「一条工作流里同时加载多个大模型」的写法，避免频繁切换。
3. 重启 ComfyUI 进程是最直接的缓解方式；出现频率高就固定一次性加载一种模型出图。
4. 网上流传的 PYTORCH_CUDA_ALLOC_CONF 环境变量在不同 Python/PyTorch 版本与平台上支持情况不一，是否生效以启动日志为准，不要盲目照抄。

14. Windows 长路径 / 中文路径问题

报错原文片段：error: unable to create file ...: Filename too long（git 克隆时报）；或自定义节点报 [Errno 2] No such file or directory；或 UnicodeDecodeError: 'gbk' codec can't decode byte ...。

原因：Windows 默认 260 字符路径限制，以及部分插件用系统默认编码读取中文路径。

解决步骤：

1. 最省事的办法：把 ComfyUI 放在短英文路径，例如 D:\AI\ComfyUI，模型别嵌太深的子目录。
2. git 克隆长路径仓库时启用长路径支持：git config --global core.longpaths true。
3. 系统级开启长路径（需管理员 PowerShell，改完重启）：

   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name LongPathsEnabled -Value 1 -PropertyType DWord -Force

4. 仍然报编码错误时，把插件目录名和模型文件名里的中文/空格去掉再试。

四、界面与出图质量类

15. 升级后界面没变化（浏览器缓存）

现象：代码已经更新，但界面还是旧样子、新节点搜不到、设置不生效。

原因：浏览器缓存了旧的前端资源；也常见于用旧标签页访问新启动的服务。

解决步骤：

1. 在 ComfyUI 页面按 Ctrl + F5 强制刷新（不是普通 F5）。
2. 仍不行就关闭标签页重新打开 http://127.0.0.1:8188；换用 localhost:8188 或反之再试一次。
3. 检查前端包是否真的升级了：pip show comfyui-frontend-package（便携版用 .\python_embeded\python.exe -m pip show comfyui-frontend-package），版本号应与当前 requirements.txt 一致。
4. 最后手段：清理该站点的浏览器数据（会同时清掉未保存的临时工作流，先导出重要工作流）。

16. 出图全黑 / 全噪点

现象：能跑完、不报错，但输出是纯黑、纯色或全是噪点。

原因（按概率排序）：VAE 与模型不匹配；用了 --fp16-vae（官方明确标注可能导致纯黑图）；分辨率超出模型训练范围；模型与 LoRA 世代不符；采样参数被改坏。

解决步骤：

1. 先去掉启动参数里的 --fp16-vae / --force-fp16 复跑一次。
2. 确认 VAE 来源：checkpoint 自带的 VAE 优先；单独加载 VAE 时要与模型同世代。
3. 分辨率回到基础档（SD1.5：512 档；SDXL / Flux：1024 档），宽度高度都取 8 的倍数。
4. 把 LoRA 权重降到 0 或直接断开，验证是否是 LoRA 冲突。
5. 换回默认工作流/官方模板重跑，能出图说明是工作流本身的问题。

17. 中文提示词乱码 / 字体缺字（PIL 报错）

报错原文片段：OSError: cannot open resource（出现在需要在图片上绘制文字的节点，如文本叠加、水印、标注类插件）；界面上的乱码则表现为方框或问号。

原因：PIL 按路径加载字体文件失败（字体不存在或路径含中文）；界面乱码属于字体/前端刷新问题。

解决步骤：

1. 给该节点指定系统中文字体文件的实际路径，例如 C:\Windows\Fonts\msyh.ttc（微软雅黑）或 C:\Windows\Fonts\simhei.ttf（黑体），确认文件存在。
2. 字体路径不要放中文目录；日志里出现 cannot open resource 就是路径没找到，逐字核对。
3. 界面乱码：先 Ctrl + F5 强刷；再看设置里的语言/Locale 选项，改成中文或跟随浏览器语言（不同前端版本菜单位置略有差异）；系统缺中文字体时先安装字体再刷新。
4. 提示词本身建议写英文，并避免在节点文本里混入全角符号；需要中文注释时用节点重命名/备注功能。

18. 浏览器打不开 127.0.0.1:8188

现象：浏览器提示「无法访问此网站」或 ERR_CONNECTION_REFUSED，但命令行窗口看起来是正常的。

原因：服务实际没起来（控制台里有报错被刷过去了）、端口被改过、系统代理把本机地址也代理走了。

解决步骤：

1. 回到命令行窗口往上翻，确认出现 To see the GUI go to: http://127.0.0.1:8188；出现的是别的端口就用那个地址。
2. 命令行里验证服务：

   curl -I http://127.0.0.1:8188

   返回 200 说明服务正常，问题在浏览器或代理；返回失败说明服务没起来，往上找报错。

3. 关闭系统代理/代理软件，或在其规则里把 localhost、127.0.0.1 加入直连名单。
4. 局域网访问时要用 --listen 启动，并放行 Windows 防火墙提示，用 http://电脑IP:8188 访问。

---

排查通用套路，最后再重复一次：先读完整报错 → 禁用全部插件确认是否核心问题 → 一次只改一个变量复现 → 记录改动前后结果。仍然解决不了，去官方文档的故障排查章节检索报错关键词，或用报错原文搜索（不要只搜中文描述）。相关阅读：安装篇、工作流与模型管理、显存与速度调优。