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

Use this page when you do not yet know which failure family you are in: startup failure, plugin import failure, dependency conflict, missing nodes, or a model placement/runtime issue. If you already know the exact error string, the narrower page is usually faster.

Decision 1: Can ComfyUI start?

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

Yes → 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 and GPU Compatibility
- Installation guides: Desktop, Portable, Manual

Decision 2: Workflow shows missing nodes

Step 1: Is it a frontend-only node? These don't need backend registration and should be ignored: Note, Reroute, MarkdownNote, Fast Groups Muter (rgthree), Fast Groups Bypasser (rgthree), PrimitiveNode, GetNode, SetNode, and anything starting with workflow>.

Step 2: Is the plugin installed? Check whether the folder exists in custom_nodes/.

Folder doesn't exist → install the correct plugin. See Custom Nodes.
Folder exists but node is still missing → go to Decision 3.

Also see How to Fix Missing Nodes in ComfyUI Workflows.

Decision 3: Plugin exists but node doesn't work

Check the startup log for IMPORT FAILED.

Missing Python package → 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.
Code error (AttributeError, ImportError on internal API) → source compatibility issue. Update the plugin (git pull) or apply a minimal patch. Do NOT keep installing packages.
No import failure, but node name doesn't match → node name migration (e.g., InpaintCrop → InpaintCropImproved). Update the workflow to the new name or add an alias in the plugin's __init__.py. See Plugin Management — Handling Node Name Changes.

For repeated IMPORT FAILED, see Plugin Import Failed and Dependency Conflicts.

Decision 4: Node exists but errors on execution

Error mentions a model file path (checkpoint, LoRA, ControlNet, SAM, ONNX) → model issue. Download the model and place it in the correct folder. See Download Models. Do NOT change plugins or dependencies for this.
Error mentions a Python module or function → may still be a dependency or compatibility issue. Check pip show <package_name> and version compatibility.

Decision 5: Log shows "Starting server" but UI won't load

The core started, but something after startup is blocking the UI.

Cause	Symptom	Fix
ComfyUI-Manager pulling remote data	Repeated attempts to reach `raw.githubusercontent.com`	Set Manager to offline mode in `config.ini`: `network_mode = offline`
BizyAir API retry loop	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 spikes, browser unresponsive	Disable Node 2.0 rendering in rgthree settings
Encoding errors	`UnicodeDecodeError` in logs	Add `PYTHONUTF8=1` and `PYTHONIOENCODING=utf-8`

Verify: can you reach http://127.0.0.1:8188/system_stats directly? If yes, the core is fine and the problem is frontend/post-startup. If python.exe died, check the last error before the crash.

Decision 6: Everything works but feels unstable

Run pip check. In a multi-plugin environment it often shows warnings — not all 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` for 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

If instability followed several package repairs, see Repair ComfyUI Portable Dependencies One Missing Module At A Time.

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>` in the right Python
`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	`--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	Use Torch Missing to select the correct wheel

Workflow Environment Setup — full SOP for complex environments
Plugin Management — node mapping, repo migrations, Git LFS traps
Dependency Conflicts
Common Issues
GPU Compatibility

Source References

Start free with Wonderful Launcher if this affects your real ComfyUI environment. It keeps launcher-native repair, task logs, and runtime checks in one place; credits are only for image generation and metered tools.

Download Wonderful Launcher See credit packages

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 whether http://127.0.0.1:8188/system_stats returns data.

Yes → 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 and GPU Compatibility
- Installation guides: Desktop, Portable, Manual

Decision 2: Workflow shows missing nodes

Step 2: Is the plugin installed? Check whether the folder exists in custom_nodes/.

Folder doesn't exist → install the correct plugin. See Custom Nodes.
Folder exists but node is still missing → go to Decision 3.

Also see How to Fix Missing Nodes in ComfyUI Workflows.

Decision 3: Plugin exists but node doesn't work

Check the startup log for IMPORT FAILED.

Missing Python package → 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.
Code error (AttributeError, ImportError on internal API) → source compatibility issue. Update the plugin (git pull) or apply a minimal patch. Do NOT keep installing packages.
No import failure, but node name doesn't match → node name migration (e.g., InpaintCrop → InpaintCropImproved). Update the workflow to the new name or add an alias in the plugin's __init__.py. See Plugin Management — Handling Node Name Changes.

For repeated IMPORT FAILED, see Plugin Import Failed and Dependency Conflicts.

Decision 4: Node exists but errors on execution

Error mentions a model file path (checkpoint, LoRA, ControlNet, SAM, ONNX) → model issue. Download the model and place it in the correct folder. See Download Models. Do NOT change plugins or dependencies for this.
Error mentions a Python module or function → may still be a dependency or compatibility issue. Check pip show <package_name> and version compatibility.

Decision 5: Log shows "Starting server" but UI won't load

The core started, but something after startup is blocking the UI.

Cause	Symptom	Fix
ComfyUI-Manager pulling remote data	Repeated attempts to reach `raw.githubusercontent.com`	Set Manager to offline mode in `config.ini`: `network_mode = offline`
BizyAir API retry loop	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 spikes, browser unresponsive	Disable Node 2.0 rendering in rgthree settings
Encoding errors	`UnicodeDecodeError` in logs	Add `PYTHONUTF8=1` and `PYTHONIOENCODING=utf-8`

Verify: can you reach http://127.0.0.1:8188/system_stats directly? If yes, the core is fine and the problem is frontend/post-startup. If python.exe died, check the last error before the crash.

Decision 6: Everything works but feels unstable

Run pip check. In a multi-plugin environment it often shows warnings — not all 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` for 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

If instability followed several package repairs, see Repair ComfyUI Portable Dependencies One Missing Module At A Time.

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>` in the right Python
`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	`--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	Use Torch Missing to select the correct wheel

Workflow Environment Setup — full SOP for complex environments
Plugin Management — node mapping, repo migrations, Git LFS traps
Dependency Conflicts
Common Issues
GPU Compatibility

Source References

Download Wonderful Launcher See credit packages

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: Log shows "Starting server" but UI won't load

Decision 6: Everything works but feels unstable

Quick reference: error → category

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: Log shows "Starting server" but UI won't load

Decision 6: Everything works but feels unstable

Quick reference: error → category

Source References

Table of Contents