comfyui-troubleshooter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ComfyUI Troubleshooter

ComfyUI故障排查工具

Diagnoses and resolves ComfyUI issues across four categories: server errors, workflow errors, quality issues, and performance problems.

诊断并解决ComfyUI四大类问题：服务器错误、工作流错误、质量问题及性能问题。

Diagnosis Process

诊断流程

Step 1: Classify the Error

步骤1：错误分类

Category	Symptoms	First Check
Server	Connection refused, timeouts, crashes	Is ComfyUI running? Check `/system_stats`
Workflow	Node errors, missing inputs, type mismatches	Validate workflow against inventory
Quality	Artifacts, wrong identity, blurry output	Check settings (CFG, weights, resolution)
Performance	OOM, slow generation, VRAM errors	Check VRAM usage, model sizes

类别	症状	首要检查项
服务器	连接被拒绝、超时、崩溃	ComfyUI是否在运行？检查 `/system_stats`
工作流	节点错误、输入缺失、类型不匹配	对照清单验证工作流
质量	伪影、身份不符、输出模糊	检查设置（CFG、权重、分辨率）
性能	内存不足（OOM）、生成速度慢、显存错误	检查显存使用情况、模型大小

Step 2: Gather Context

步骤2：收集上下文信息

Collect before diagnosing:

Error message (exact text)
Workflow being executed (or description)
Models involved (checkpoint, LoRA, ControlNet, etc.)
Settings (CFG, steps, resolution, sampler)
Hardware (from
```
foundation/hardware-profile.md
```
)
Inventory (from
```
state/inventory.json
```
)

诊断前需收集：

错误信息（精确文本）
正在执行的工作流（或描述）
涉及的模型（checkpoint、LoRA、ControlNet等）
设置参数（CFG、步数、分辨率、采样器）
硬件信息（来自
```
foundation/hardware-profile.md
```
）
安装清单（来自
```
state/inventory.json
```
）

Step 3: Match Error Pattern

步骤3：匹配错误模式

See

references/troubleshooting.md

for the full error database.

完整错误数据库请查看

references/troubleshooting.md

。

Quick Fix Reference

快速修复参考

Top 10 Most Common Errors

十大常见错误

1. "CUDA out of memory" → Use FP8:

--fp8_e4m3fn-unet

→ Enable tiled VAE → Reduce resolution → Restart ComfyUI (clears fragmentation)

2. "Node type not found: {name}" → Install the custom node package via ComfyUI-Manager → Check

comfyui-inventory

node-to-package mapping

3. "Expected scalar type BFloat16 but found Float" → Precision mismatch. Add

--force-fp16

or use matching precision nodes

4. Burned/overexposed faces → Lower CFG to 4-5 (InstantID) → Reduce identity method weight → Add noise to negative embeds (35%)

5. "No model found at path" → Check filename spelling (exact match required) → Verify file is in correct subdirectory → Run inventory scan to confirm

6. Watermark artifacts at 1024x1024 → Use 1016x1016 or 1020x1020 instead

7. Identity doesn't match reference → Use higher quality reference image (clear, front-facing) → Increase IP-Adapter weight to 0.8+ → Verify InsightFace antelopev2 is installed

8. Video flickering → Lower FaceDetailer denoise to 0.3 → Add deflicker post-processing → Increase AnimateDiff context overlap to 4+

9. Queue stuck/not processing → POST

/interrupt

to cancel → POST

/free

to unload models → Restart ComfyUI

10. Slow generation → Check if

--lowvram

is enabled (remove it on RTX 5090) → Use

--highvram

instead → Update cuDNN to 8800+ → Enable SageAttention for Wan models

1. "CUDA out of memory" → 使用FP8：

--fp8_e4m3fn-unet

→ 启用分块VAE → 降低分辨率 → 重启ComfyUI（清除内存碎片）

2. "Node type not found: {name}" → 通过ComfyUI-Manager安装自定义节点包 → 查看

comfyui-inventory

的节点-包映射关系

3. "Expected scalar type BFloat16 but found Float" → 精度不匹配。添加

--force-fp16

或使用匹配精度的节点

4. 人脸过曝/灼伤 → 将CFG降至4-5（InstantID） → 降低身份识别方法的权重 → 为负嵌入添加35%的噪声

5. "No model found at path" → 检查文件名拼写（要求完全匹配） → 验证文件是否在正确的子目录中 → 运行清单扫描确认

6. 1024x1024分辨率下出现水印伪影 → 改用1016x1016或1020x1020分辨率

7. 身份与参考图不符 → 使用更高质量的参考图（清晰、正面） → 将IP-Adapter权重提高到0.8以上 → 确认已安装InsightFace antelopev2

8. 视频闪烁 → 将FaceDetailer降噪值降至0.3 → 添加去闪烁后处理 → 将AnimateDiff上下文重叠度提高到4以上

9. 队列停滞/不处理任务 → 发送POST请求

/interrupt

取消任务 → 发送POST请求

/free

卸载模型 → 重启ComfyUI

10. 生成速度慢 → 检查是否启用了

--lowvram

（RTX 5090请移除该参数） → 改用

--highvram

→ 将cuDNN更新至8800+ → 为Wan模型启用SageAttention

Decision Tree: Quality Issues

质量问题决策树

OUTPUT LOOKS WRONG
    |
    |-- Faces look wrong
    |   |-- Too smooth/plastic → Add skin texture LoRA (0.2-0.4)
    |   |-- Wrong identity → Increase identity weight, check reference quality
    |   |-- Burned/hot → Lower CFG to 4-5, reduce InstantID weight
    |   |-- Deformed → Add "bad anatomy, deformed" to negative
    |   |-- Different every time → Fix seed, add LoRA for consistency
    |
    |-- Colors wrong
    |   |-- Oversaturated → Lower CFG, add "oversaturated" to negative
    |   |-- Washed out → Check VAE is loaded, try different scheduler
    |   |-- Color shift in video → Add color correction post-processing
    |
    |-- Resolution/sharpness
    |   |-- Blurry → Increase steps (25-30), check resolution matches model
    |   |-- Pixelated → Use proper upscaler (4x-UltraSharp), not resize
    |   |-- Artifacts → Lower denoise, check for model corruption
    |
    |-- Composition
    |   |-- Ignoring prompt → Increase CFG slightly, simplify prompt
    |   |-- Extra limbs/objects → Add to negative prompt, use ControlNet
    |   |-- Wrong pose → Add ControlNet OpenPose with reference

输出结果异常
    |
    |-- 人脸效果异常
    |   |-- 过于光滑/塑料感 → 添加皮肤纹理LoRA（权重0.2-0.4）
    |   |-- 身份不符 → 提高身份权重，检查参考图质量
    |   |-- 过曝/高亮 → 将CFG降至4-5，降低InstantID权重
    |   |-- 畸形 → 在负提示词中加入“bad anatomy, deformed”
    |   |-- 每次结果不同 → 固定种子，添加LoRA保证一致性
    |
    |-- 颜色异常
    |   |-- 饱和度偏高 → 降低CFG，在负提示词中加入“oversaturated”
    |   |-- 色彩暗淡 → 检查VAE是否加载，尝试不同的调度器
    |   |-- 视频色彩偏移 → 添加色彩校正后处理
    |
    |-- 分辨率/锐度问题
    |   |-- 模糊 → 增加步数（25-30），检查分辨率是否匹配模型
    |   |-- 像素化 → 使用合适的超分模型（4x-UltraSharp），而非简单缩放
    |   |-- 伪影 → 降低降噪值，检查模型是否损坏
    |
    |-- 构图问题
    |   |-- 忽略提示词 → 略微提高CFG，简化提示词
    |   |-- 多余肢体/物体 → 添加到负提示词，使用ControlNet
    |   |-- 姿势错误 → 使用带参考图的ControlNet OpenPose

Missing Dependency Resolution

缺失依赖项解决方法

When a workflow references something not in inventory:

当工作流引用了清单中没有的内容时：

Missing Custom Node

缺失自定义节点

1. Identify package from class_type (see inventory skill's mapping)
2. Suggest: "Open ComfyUI-Manager → Search → Install {package_name}"
3. Alternative: "cd {ComfyUI}/custom_nodes && git clone {repo_url}"
4. Remind: Restart ComfyUI after installation

1. 根据class_type识别包（查看清单技能的映射关系）
2. 建议：“打开ComfyUI-Manager → 搜索 → 安装{package_name}”
3. 替代方案：“cd {ComfyUI}/custom_nodes && git clone {repo_url}”
4. 提醒：安装后重启ComfyUI

Missing Model

缺失模型

1. Look up in references/models.md for download link
2. Provide: exact filename, download URL, target directory
3. For large models (>10GB): suggest HF CLI for reliability
   "huggingface-cli download {repo} {file} --local-dir {path}"

1. 在references/models.md中查找下载链接
2. 提供：精确文件名、下载URL、目标目录
3. 对于大型模型（>10GB）：建议使用HF CLI以保证可靠性
   "huggingface-cli download {repo} {file} --local-dir {path}"

Version Incompatibility

版本不兼容

1. Check ComfyUI version vs node package requirements
2. Suggest: "cd {ComfyUI} && git pull" for ComfyUI update
3. Or: pin specific node version if newest breaks things

1. 检查ComfyUI版本与节点包的要求是否匹配
2. 建议：“cd {ComfyUI} && git pull”以更新ComfyUI
3. 或：如果最新版本导致问题，固定特定节点版本

Escalation

升级处理

If troubleshooting doesn't resolve the issue:

Check ComfyUI GitHub Issues for known bugs
Check specific node package's Issues
Search r/comfyui for community solutions
Suggest posting in ComfyUI Discord with error details

如果故障排查无法解决问题：

查看ComfyUI GitHub Issues中的已知bug
查看特定节点包的Issues
在r/comfyui中搜索社区解决方案
建议在ComfyUI Discord中发布包含错误详情的帖子

Reference

参考资料

```
references/troubleshooting.md
```
- Full error database with solutions
```
state/inventory.json
```
- Current installation state
```
references/models.md
```
- Model download links and paths

```
references/troubleshooting.md
```
- 包含解决方案的完整错误数据库
```
state/inventory.json
```
- 当前安装状态
```
references/models.md
```
- 模型下载链接及路径