ComfyUI Broken? Troubleshooting Decision Tree

Systematic diagnosis for broken ComfyUI — identify whether the problem is a startup crash, plugin conflict, dependency error, or model issue.

Tested Environment

OS: Windows 10 / 11
Launcher: Wonderful Launcher v1.x
ComfyUI: Portable / Managed install
Python: 3.11+
CUDA / Torch: CUDA 12.x / Torch 2.x
Last tested: 2026-05-19

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.
Do not run pip install -r requirements.txt blindly.
1. Confirm which Python environment is active (where python or which python)
2. Inspect requirements.txt — check if it pins torch, numpy, or opencv versions
3. Install only the missing package when possible: pip install <package-name>
4. Run pip check after installation to verify no conflicts were introduced
- 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:

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
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

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, try Wonderful Launcher first. It's free and can recover the environment automatically.

Source References

Start with Wonderful Launcher if this issue touches your real ComfyUI environment. Use the docs to understand the fix, and use the app to inspect the machine you already have.

Download Wonderful Launcher

Did this fix your issue?

Your answer helps prioritize verified ComfyUI repairs.

Tested Environment

OS: Windows 10 / 11
Launcher: Wonderful Launcher v1.x
ComfyUI: Portable / Managed install
Python: 3.11+
CUDA / Torch: CUDA 12.x / Torch 2.x
Last tested: 2026-05-19

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.
Do not run pip install -r requirements.txt blindly.
1. Confirm which Python environment is active (where python or which python)
2. Inspect requirements.txt — check if it pins torch, numpy, or opencv versions
3. Install only the missing package when possible: pip install <package-name>
4. Run pip check after installation to verify no conflicts were introduced
- 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:

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
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

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, try Wonderful Launcher first. It's free and can recover the environment automatically.

Source References

Start with Wonderful Launcher if this issue touches your real ComfyUI environment. Use the docs to understand the fix, and use the app to inspect the machine you already have.

Download Wonderful Launcher

Did this fix your issue?

Your answer helps prioritize verified ComfyUI repairs.

ComfyUI Broken? Troubleshooting Decision Tree

Decision 1: Can ComfyUI Start?

Decision 2: Workflow Shows Missing Nodes

Decision 3: Plugin Exists But Node Doesn't Work

Decision 4: Node Exists But Errors on Execution

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

Decision 6: Everything Works But Environment Feels Unstable

Quick Reference: Error → Category

Still Stuck?

Source References

Table of Contents

ComfyUI Broken? Troubleshooting Decision Tree

Decision 1: Can ComfyUI Start?

Decision 2: Workflow Shows Missing Nodes

Decision 3: Plugin Exists But Node Doesn't Work

Decision 4: Node Exists But Errors on Execution

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

Decision 6: Everything Works But Environment Feels Unstable

Quick Reference: Error → Category

Still Stuck?

Source References

Table of Contents