Troubleshooting Decision Tree

When something goes wrong in ComfyUI, the most common mistake is guessing. This guide provides a structured decision tree for diagnosing issues based on real-world experience with hundreds of environments.

Decision 1: Can ComfyUI Start?

Check if http://127.0.0.1:8188/system_stats returns data.

• Yes → ComfyUI core is working. Go to Decision 2.
• No → Fix the base environment first. Do NOT install plugins yet.
  • Check: Is Python found? Is PyTorch installed with CUDA? Is the right run_nvidia_gpu.bat being used?
  • See Common Issues for specific error fixes
  • Check GPU Compatibility for driver and CUDA version matching
  • Review installation guides: Desktop, Portable, Manual

Decision 2: Workflow Shows Missing Nodes

After importing a workflow, some nodes appear red or missing.

Step 1: Is it a frontend-only node?

These nodes don't need backend registration and should be ignored:

• Note, Reroute, MarkdownNote
• Fast Groups Muter (rgthree), Fast Groups Bypasser (rgthree)
• PrimitiveNode, GetNode, SetNode
• Anything starting with workflow> (workflow-local wrappers)

If it's one of these → Not a real problem. Ignore it.

Step 2: Is the plugin installed?

Check if the plugin folder exists in custom_nodes/.

• Plugin folder doesn't exist → Install the correct plugin. See Custom Nodes.
• Plugin folder exists but node is still missing → Go to Decision 3.

Decision 3: Plugin Exists But Node Doesn't Work

The plugin directory is there, but the node still doesn't show up in ComfyUI.

Check the startup log for IMPORT FAILED.

• Import failed due to missing Python package → This is a dependency issue.

  • Run pip install -r requirements.txt inside the plugin folder
  • Check for version conflicts with pip check
  • See Dependency Conflicts for advanced resolution

• Import failed due to code error (AttributeError, ImportError on internal API) → This is a source compatibility issue.

  • The plugin code is incompatible with your ComfyUI version
  • Either update the plugin (git pull) or apply a minimal patch
  • This is NOT a dependency problem — don't keep installing packages

• No import failure, but node name doesn't match → This is a node name migration.

  • The plugin was updated and renamed its nodes
  • Example: InpaintCrop → InpaintCropImproved
  • Solution: Update the workflow to use the new node name, or add an alias in the plugin's __init__.py. See Plugin Management — Handling Node Name Changes

Decision 4: Node Exists But Errors on Execution

The node shows up (not red), but throws an error when you run the workflow.

Check the error message:

• Error mentions a model file path (checkpoint, LoRA, ControlNet, SAM, ONNX, etc.) → This is a model issue, not a plugin issue.

  • Download the required model and place it in the correct folder
  • See Download Models
  • Do NOT change plugins or dependencies for this

• Error mentions Python module or function → May still be a dependency or compatibility issue.

  • Check if the required package is installed: pip show <package_name>
  • Check version compatibility

Decision 5: ComfyUI Log Shows "Starting server" But UI Won't Load

The console shows Starting server and To see the GUI go to: http://127.0.0.1:8188, but the browser stays on a loading screen.

This does NOT mean ComfyUI failed to start. The core started, but something after startup is blocking the UI.

Common culprits:

Cause	Symptom	Fix
ComfyUI-Manager pulling remote data	Log shows repeated attempts to reach raw.githubusercontent.com	Set Manager to offline mode in config.ini: network_mode = offline
BizyAir API retry loop	Log shows repeated Failed to cache trd models and Invalid API key	Set BIZYAIR_SKIP_TRD_MODEL_CACHE=1 in your launch script
Large workflow + Node 2.0 rendering	CPU usage spikes, browser becomes unresponsive	Disable Node 2.0 rendering in rgthree settings
Encoding errors	UnicodeDecodeError in logs	Add PYTHONUTF8=1 and PYTHONIOENCODING=utf-8 to your environment

Verification steps:

1. Can you access http://127.0.0.1:8188/system_stats directly? If yes → core is fine, problem is in frontend or post-startup plugins
2. Is the python.exe process still alive? If it died → check the last error in the log before it crashed

Decision 6: Everything Works But Environment Feels Unstable

ComfyUI runs, workflows load, but you get random crashes or package conflicts.

Run pip check to find dependency conflicts.

Important: In a ComfyUI environment with many plugins, pip check will often show warnings. Not all of them are real problems:

Type	What It Means	Action
Hard blocker	Core packages incompatible (e.g., torch version mismatch)	Fix immediately
Soft drift	Plugin declares numpy>=2 but you're on numpy 1.26.4 to protect stability	Record it, but don't fix if runtime works
Optional dependency	A plugin wants a package your workflows don't use	Don't install — it may destabilize your environment

Quick Reference: Error → Category

Error Type	Category	What to Do
Red/missing node	Plugin not installed or import failed	Install plugin, check import logs
IMPORT FAILED in log	Dependency or compatibility issue	Check pip install, version conflicts
ModuleNotFoundError	Missing Python package	pip install <package>
AttributeError on ComfyUI internal API	Plugin incompatible with ComfyUI version	Update plugin or patch
FileNotFoundError on model path	Missing model file	Download the model
CUDA out of memory	GPU VRAM insufficient	Use --lowvram, smaller model, or lower resolution. See GPU Compatibility
Blank browser / stuck splash	Post-startup blocking	Check for network plugins, set offline mode
torch.cuda.is_available() returns False	PyTorch CUDA mismatch	Reinstall PyTorch with correct CUDA version

Related Guides

• Workflow Environment Setup — The full 7-stage SOP for complex environments
• Plugin Management — Node mapping, repo migrations, Git LFS traps
• Dependency Conflicts — Deep dive into Python dependency resolution
• Common Issues — Quick fixes for frequent problems
• GPU Compatibility — Full driver, CUDA, and PyTorch version matrix

Still Stuck?

If you've followed this tree and can't resolve the issue, book a remote fix session. Our experts handle these exact diagnosis paths every day.