troubleshooting

ComfyUI 故障排查指南

渲染已完成，但效果不对（出现瑕疵、主体／姿势／颜色错误、ControlNet／蒙版／LoRA 未生效，或细化器导致效果变差）？这不是错误。 使用调试渲染技能（通过 list_packs 执行 action: "skill_read"， name: "debug-render"），通过 panel_run 的 to_node_id 逐节点定位问题阶段， 预览中间步骤。本指南适用于运行失败并报错、出现 OOM 或缺少节点的情况。

错误诊断策略

工作流失败时，请按以下步骤排查：

1. 获取错误。使用 get_history(action="diagnose") 检索执行结果，其中包含完整的回溯信息，以及缺失的模型／节点
2. 检查日志。使用 get_system_stats (action:"logs")，并通过 "error"、"warning"、"traceback" 等关键词筛选
3. 找出失败节点。历史记录响应中包含失败节点的 node_id 和 node_type
4. 交叉核对输入。使用 create_workflow (action:"node_info") 验证失败节点所需的输入架构
5. 检查模型。使用 list_local_models 验证所有引用的模型文件是否存在

内存不足（OOM）

错误模式

torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate X MiB.
GPU 0 has a total capacity of 24.00 GiB of which X MiB is free.

或者：

RuntimeError: CUDA error: out of memory

根本原因

GPU 没有足够的显存，无法同时容纳模型权重、中间张量和潜像。常见诱因包括：

• 高分辨率图像（2048x2048 及以上）
• 同时加载多个模型
• 显存有限时使用 FP32 精度模型
• 生成视频（LTXV、AnimateDiff）且帧数较多
• 批次大小过大

修复方法（按优先顺序排列）

1. 降低分辨率。降至模型的原生分辨率（SD 1.5 为 512，SDXL／Flux 为 1024）
2. 使用 FP8／FP16 量化模型。FP8 Flux 模型约占用 8GB，FP16 则约占用 24GB
   • 搜索 FP8 变体：download_model({ action: "search", query: "flux fp8" })，或将 "sdxl fp8" 用作查询词
3. 启动标志（显存阶梯）。通过 ComfyUI CLI 标志将内容卸载到其他位置：
   • --lowvram 将文本编码器／模型部件卸载到 CPU
   • --novram 会进行极限卸载，是长视频（LTX 2／WAN）出现 OOM 时的首选
   • --cache-none 不缓存任何内容（RAM／显存占用最低）；可与 --novram 组合使用
   • --reserve-vram N 预留 N GB 显存，让 GPU 不会转而使用速度较慢的共享显存（Windows）；通常设置为 2 至 4
   • --disable-smart-memory 在运行卡住或间歇性出现 OOM 时，强制将内容卸载到 RAM
   • 完整的标志组合与配置方案：comfyui-launch-flags
4. 在生成之间释放显存。ComfyUI 应会自动管理，但重启可以清除泄漏的内存
5. 使用分块 VAE 解码。对于高分辨率图像，将 VAE 解码步骤分块处理
   • 节点：使用 VAEDecodeTiled 代替 VAEDecode
   • 将图像分成多个区块，分别解码后再拼接
6. 减小批次大小。在 EmptyLatentImage 中将 batch_size 设为 1
7. 避免使用多个模型。不要同时加载两个完整检查点；改用一个检查点和多个 LoRA
8. 对于 LTXV／视频：在 24GB 显卡上始终使用 FP8 量化视频模型

显存估算

模型	FP32	FP16	FP8
SD 1.5	~4GB	~2GB	~1GB
SDXL	~12GB	~6GB	~3GB
Flux Dev	~48GB	~24GB	~12GB
Flux Schnell	~48GB	~24GB	~12GB
LTXV	~20GB+	~10GB+	~6GB

启动标志 — 显存／缓存／注意力／精度

ComfyUI 的启动标志可调整速度与显存之间的权衡。请根据检测到的 GPU 进行匹配（面板编排器会在其环境信息块中报告 VRAM／GPU／torch／sage；据此选择 对应档位）。请将这些标志设置在启动 ComfyUI 的进程上（或设置到 --panel-orchestrator／connect 命令启动的 ComfyUI 上，而不是 Agent 上）。

VRAM 模式（按显卡容量选择一种）

标志	显卡容量	行为
--gpu-only	16GB 以上	所有内容（CLIP/VAE/UNet）都保留在 GPU 上——速度最快，VRAM 占用最高
--highvram	12–16GB	模型使用后仍驻留在 GPU 上，不卸载到 CPU
--normalvram	8–12GB	默认均衡模式——空闲时卸载到 CPU RAM
--lowvram	6–8GB	拆分 UNet，大量卸载到 CPU——速度较慢
--novram	4–6GB	极限拆分/卸载——适用于低 VRAM 模式下仍出现 OOM，或处理长视频
--cpu	<4GB / 无 GPU	仅使用 CPU（非常慢）

--reserve-vram N（GB）会预留空间给操作系统和其他应用。如果运行中途偶尔出现 OOM（VAE 解码 / 音频往返会造成峰值），请调高该值。

缓存（RAM 占用与重新运行速度）

标志	效果
--cache-classic	默认的激进缓存（重新运行最快，RAM 占用最高）
--cache-lru N	保留最近 N 个节点结果（限制 RAM 占用）
--cache-ram N	将缓存限制在 N GB 可用空间内
--cache-none	不缓存——RAM 占用最低，每次都重新运行所有节点

注意力机制（速度与兼容性）

标志	说明
--use-sage-attention	推荐——快速且高效（需要 SageAttention 和 Triton；参见 triton-sageattention）
--use-flash-attention	在支持的 GPU 上速度非常快
--use-pytorch-cross-attention	PyTorch 2.x 原生实现——兼容性最佳
--use-split-cross-attention	VRAM 占用较低，速度较慢
--use-quad-cross-attention	次二次优化
（省略）	如果可用，则自动选择 xFormers

精度（UNet）

标志	效果
--fp16-unet	半精度，约占用 50% VRAM
--bf16-unet	BFloat16，均衡表现（较新的 GPU）
--fp8_e4m3fn-unet	8 位浮点，节省最多（最新的 GPU）

常用配置：

• RTX 4090/5090（24 至 32GB）：--gpu-only --use-sage-attention --cache-classic
• 12 至 16GB：--highvram --use-sage-attention（大型模型可选 --fp8_e4m3fn-unet）
• 8GB：--normalvram --use-sage-attention --cache-lru 20
• 6GB：--lowvram --use-split-cross-attention --cache-none
• 处理长视频时出现 OOM：--novram --reserve-vram 2

设备不匹配

错误模式

RuntimeError: Expected all tensors to be on the same device, but found at least
two devices, cuda:0 and cpu!

根本原因

CPU 上的张量与 GPU 上的张量被组合在一起。通常由以下情况导致：

• 自定义节点未将张量移动到正确的设备
• 模型卸载导致部分模型位于 CPU 上
• 节点生成 CPU 张量，而下游节点需要 GPU 张量

解决方法

1. 检查错误是否由特定自定义节点引起。更新或替换该节点
2. 如果使用 --lowvram 或 --cpu，某些节点可能不支持卸载到 CPU
3. 重启 ComfyUI 以重置设备状态
4. 检查自定义节点是否有修复设备处理问题的新版本

缺少节点

错误模式

Cannot find node class 'NodeClassName'

或在执行响应中：

"error": {"type": "node_not_found", "message": "Cannot find node class 'X'"}

根本原因

工作流引用了尚未安装的节点类型。通常由以下情况导致：

• 未安装自定义节点包
• 已安装自定义节点包，但加载失败（导入错误）
• 节点在节点包更新后被重命名或移除

解决方法

1. 搜索节点包：

   search_custom_nodes(action="search", query="NodeClassName")
   

2. 通过 ComfyUI Manager 或注册表安装
3. 检查日志中的导入错误：

   get_system_stats (action:"logs")(keyword="import")
   get_system_stats (action:"logs")(keyword="error")
   

   导入错误通常能指出缺少的 Python 依赖项
4. 安装缺少的 Python 依赖项。如果自定义节点需要 pip 包：

   pip install missing-package
   

5. 安装任何自定义节点后都要重启 ComfyUI。节点会在启动时加载

NaN 张量错误

错误模式

RuntimeError: Input contains NaN

或者图像呈现为纯灰色/噪点，且日志中有 NaN 警告。

根本原因

扩散过程中出现数值不稳定。常见诱因：

• CFG scale 过高。数值超过 15–20 可能导致数值溢出
• 模型权重损坏。下载文件损坏或合并不兼容
• FP16 溢出。某些运算在半精度下会溢出
• LoRA 不兼容。LoRA 是针对不同的基础模型训练的

修复方法

1. 降低 CFG。SD 1.5/SDXL 尝试使用 7.0，Flux 尝试使用 1.0
2. 使用 FP32 VAE。某些 VAE 在 FP16 下会产生 NaN。切换到 vae-ft-mse-840000-ema-pruned.safetensors（FP32）
3. 移除 LoRA。先在不使用 LoRA 的情况下测试，以隔离原因
4. 重新下载模型。哈希校验可以检测文件是否损坏
5. 检查 LoRA 兼容性。LoRA 必须与基础模型系列匹配

数据类型不匹配

错误模式

RuntimeError: expected scalar type Float but found Half

或者：

RuntimeError: expected scalar type Half but found Float

或者：

RuntimeError: Input type (float) and bias type (c10::Half) should be the same

根本原因

模型组件预期使用一种精度（FP32/FP16），但实际接收到的是另一种精度。最常见的情况包括：

• VAE 精度不匹配（FP16 模型 + FP32 VAE，或反之）
• 混合精度 LoRA
• 强制使用特定数据类型的自定义节点

修复方法

1. 使用单独的 VAE。加载显式指定的 FP32 VAE，而不是检查点内置的 VAE
   • 节点：使用 VAELoader 加载 vae-ft-mse-840000-ema-pruned.safetensors
2. 匹配精度。如果模型为 FP16，则全程使用兼容 FP16 的节点
3. 强制使用 FP32 VAE 解码。某些节点包提供 VAEDecodeFP32 节点
4. 检查 ComfyUI 设置。--force-fp32 标志会强制所有内容使用 FP32（会占用更多 VRAM）

CLIP Token 溢出

错误模式

没有明确的错误。提示词会在 77 个 token 处被截断，且不会发出警告，后面提到的细节会被忽略。

症状

• 长提示词后面的部分对图像没有影响
• 添加更多描述性文本不会改变输出
• 移除前面的 token 后，后面的 token 突然开始生效

修复方法

1. 使用 BREAK token。在自然的分界处拆分提示词：

   subject description, pose, clothing, setting
   BREAK
   lighting, style, quality, camera angle
   

2. 使用 CLIPTextEncodeSDXL。SDXL 的双 CLIP 会处理两个 77-token 区块
3. 优先排列重要 token。将最重要的描述词放在前面
4. 减少填充词。尽可能删除冠词和介词
5. 使用嵌入。通过文本反演将复杂概念浓缩为单个 token

黑色图像

错误模式

执行过程中没有报错。工作流“成功”运行，但生成的图像完全黑色或接近黑色。

根本原因与修复方法

原因	诊断方法	修复方法
denoise = 0	检查 KSampler 输入	txt2img 将 denoise 设为 1.0，img2img 设为 0.5-0.8
cfg = 0	检查 KSampler 输入	CFG 设为 7.0（SD 1.5）、1.0（Flux）
steps = 0	检查 KSampler 输入	steps 设为 20+（标准模式）或 4+（turbo）
VAE 错误	VAE 与模型不匹配	使用与模型系列对应的正确 VAE
提示词为空	CLIPTextEncode 的文本为空	添加文本提示词
调度器错误	调度器与采样器组合不兼容	尝试使用 "normal" 调度器和 "euler" 采样器
种子冲突	极少见	更改种子值
FP16 VAE 溢出	VAE 解码生成黑色图像	使用 FP32 VAE 或 VAEDecodeTiled

快速诊断清单

1. 检查 denoise > 0（txt2img 应设为 1.0）
2. 检查 cfg > 0（SD 1.5 应设为 7.0，Flux 应设为 1.0）
3. 检查 steps > 0（标准模式应设为 20，turbo 应设为 4）
4. 确认正向提示词不为空
5. 尝试使用其他种子
6. 尝试已知可用的采样器/调度器组合：euler + normal

连接类型错误

错误模式

Output type 'IMAGE' doesn't match input type 'LATENT'

或者：

Required input 'model' of type 'MODEL' but got connection of type 'CLIP'

根本原因

将节点的错误输出端口连接到不兼容的输入端口。通常是因为使用了错误的输出索引。

修复方法

1. 检查输出索引。使用 create_workflow (action:"node_info") 确认准确的输出顺序
   • CheckpointLoaderSimple 的输出：0=MODEL，1=CLIP，2=VAE
   • 索引错误示例：["1", 0] 表示 MODEL，["1", 1] 表示 CLIP
2. 验证连接格式。["nodeId", outputIndex]，其中节点 ID 是字符串，索引是整数
3. 检查数据类型流。管线必须遵循正确的数据类型链：

   MODEL → KSampler
   CLIP → CLIPTextEncode → CONDITIONING → KSampler
   LATENT → KSampler → LATENT → VAEDecode → IMAGE
   VAE → VAEDecode, VAEEncode
   

模型加载错误

错误模式

FileNotFoundError: [Errno 2] No such file or directory: 'models/checkpoints/model.safetensors'

或者：

SafetensorError: Error reading file: invalid header

或者：

RuntimeError: PytorchStreamReader failed reading zip archive

根本原因

• 找不到文件。引用路径下不存在模型文件
• 下载损坏。文件不完整或已损坏
• 格式错误。文件不是有效的 safetensors/pickle/checkpoint 格式

修复方法

1. 确认模型存在：list_local_models({ action: "list", model_type: "checkpoints" })
2. 检查确切的文件名。工作流中的模型名称必须与文件名完全一致（区分大小写）
3. 重新下载。如果哈希不匹配或文件损坏：

   download_model({ action: "download", url: "...", target_subfolder: "checkpoints" })
   

4. 检查文件大小。1KB 的 safetensors 文件已损坏；请重新下载
5. 确认子文件夹。模型必须放在正确的子文件夹中（checkpoints/、loras/、vae/ 等）

Torch / CUDA 版本错误

错误模式

RuntimeError: CUDA error: no kernel image is available for execution on the device

或者：

ImportError: cannot import name 'xxx' from 'torch'

或者：

AssertionError: Torch not compiled with CUDA enabled

根本原因

PyTorch 与 CUDA 版本不兼容，通常发生在以下情况之后：

• 更新 PyTorch，但未安装匹配的 CUDA 工具包
• 安装会降级或更改 PyTorch 的自定义节点
• 使用会安装仅支持 CPU 的 PyTorch 的 pip install 命令

修复方法

1. 检查当前版本：

   get_system_stats()  # Shows PyTorch version and CUDA version
   

2. 确认 CUDA 是否可用。在 Python 中运行：torch.cuda.is_available()
3. 重新安装支持 CUDA 的 PyTorch。访问 pytorch.org，获取与你的 CUDA 版本匹配的正确安装命令
4. 固定 PyTorch 版本。修复后，避免运行可能更改 PyTorch 的 pip install 命令
5. 使用 ComfyUI 自带的 venv。ComfyUI Desktop 附带预配置的 Python 环境

ComfyUI Desktop 与 CLI 的区别

主要区别

方面	ComfyUI Desktop	ComfyUI CLI
默认端口	8000	8188
Python	内嵌（捆绑）	系统/venv Python
安装位置	AppData/Local/Programs/ComfyUI/	克隆仓库的位置
自定义节点	Documents/ComfyUI/custom_nodes/	仓库中的 ./custom_nodes/
模型	Documents/ComfyUI/models/	仓库中的 ./models/
配置	用于共享路径的 extra_model_paths.yaml	相同
更新	应用内自动更新程序	git pull

常见问题

• 端口错误。MCP 工具默认使用 8188；如果使用 Desktop，请将端口配置为 8000
• 路径混淆。Desktop 将用户数据与应用程序文件分开存储
• 自定义节点的 pip 安装。Desktop 内嵌的 Python 可能不在 PATH 中；请在 venv 中安装

针对特定错误的调试命令

工作流失败 — 获取详细信息

get_history(action="list")                       # Most recent execution
get_history(action="list", prompt_id="abc-123")  # Specific execution
get_history(action="diagnose")                   # Why the last run failed

响应包含：

• status.status_str：“success” 或 “error”
• status.messages：带时间戳的执行消息
• outputs：节点输出（图像等）
• 失败节点的错误回溯信息

检查服务运行状况

get_system_stats()    # GPU info, VRAM, Python/PyTorch versions
queue(action="list")  # Running and pending jobs
get_system_stats (action:"logs")(max_lines=50, keyword="error")  # Recent error logs

确认节点是否可用

create_workflow(action="node_info", node_type="KSampler")        # Check specific node
create_workflow(action="node_info", node_type="ControlNetApply")  # Verify custom nodes loaded

确认模型

list_local_models({ action: "list", model_type: "checkpoints" })   # Installed checkpoints
list_local_models({ action: "list", model_type: "loras" })         # Installed LoRAs
list_local_models({ action: "list", model_type: "controlnet" })    # Installed ControlNets

快速参考：错误与修复方法

错误消息（部分）	最可能的修复方法
CUDA out of memory	降低分辨率，使用 FP8 模型；显存选项梯度：--lowvram → --novram --cache-none → --reserve-vram N（启动标志）
Expected all tensors on same device	更新自定义节点，重启 ComfyUI
Cannot find node class	安装节点包，重启 ComfyUI
Input contains NaN	降低 CFG，使用 FP32 VAE，移除 LoRA
expected scalar type Float but found Half	使用 FP32 VAE，或使用 --force-fp32
No such file or directory（模型）	检查文件名，重新下载模型
invalid header（safetensors）	重新下载——文件已损坏
CUDA error: no kernel image	重新安装与 CUDA 版本匹配的 PyTorch
图像全黑，没有错误	检查 denoise > 0、cfg > 0、steps > 0，且提示词不为空
图像看起来杂乱/有噪点	模型与 VAE 组合错误，或采样器设置错误
端口 8188 上出现 Connection refused	ComfyUI 未运行，或正在使用 Desktop（端口 8000）
Prompt outputs failed validation	节点输入与架构不匹配——检查 create_workflow (action:"node_info")

来源

• **官方：**未找到供应商错误目录。启动标志名称已与 comfyui-launch-flags（上游 cli_args.py）交叉核对。
• **实证：**错误→修复表基于观察到的 ComfyUI 故障整理。