Comfyui Troubleshooter

ComfyUI Troubleshooter

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

Diagnosis Process

Step 1: Classify the Error

Step 2: Gather Context

Collect before diagnosing:

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

Step 3: Match Error Pattern

See references/troubleshooting.md for the full error database.

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

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

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

Missing Model

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

Version Incompatibility

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

Escalation

If troubleshooting doesn't resolve the issue:

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

Reference

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