ComfyUI Troubleshooting: Red Nodes, VAE Errors, and Rollbacks

You open a shared workflow and find a row of red unknown nodes. You click Manager’s Install Missing Custom Nodes, restart ComfyUI, and the nodes are still red. Manager is not a universal repair tool: it manages node code, but it cannot guarantee that every dependency installs correctly, and it does not install model files.

Red nodes are only one entry point into ComfyUI troubleshooting. The app may hang on loading, the UI may stay blank, a workflow that used to run may break after an update, VAE output may turn gray or black, or a model may not appear in a dropdown. These symptoms usually point to custom-node conflicts, dependency versions, model paths, precision flags, or VRAM peaks.

The fastest route is symptom-first: match what you see, identify the likely subsystem, and make the smallest useful test.

Symptom-first quick reference

The table covers six common entry points. Match the symptom in the first column, use the second to identify the likely source, and start with the action in the third.

Symptom	Most likely cause	First action
Red nodes / unknown nodes	Missing custom node, renamed node, or failed node import	Search Manager or the Registry for the node name and check the console for Import failed
Stuck on loading / blank screen	Conflicting custom-node frontend extension	Test with python main.py --disable-all-custom-nodes
Prompt execution failed after Queue	Custom-node error, model problem, or insufficient VRAM	Open Show report and identify the failing component
Gray, white, tinted, or black VAE output	VAE mismatch or precision setting	Check the VAE loader connection, file pairing, and --fp16-vae
A workflow breaks after an update	Core/custom-node version mismatch or dependency conflict	Identify what was updated and inspect the scripts in update
A copied model is missing from the dropdown	Wrong model path or stale node definitions	Check the matching ComfyUI/models/ subfolder, then restart or refresh

Do not start by deleting the installation. Preserve the workflow, logs, node list, and versions before changing the environment.

Red-node triage: custom node or model?

A red unknown node usually means ComfyUI cannot find that node type. The custom node may be missing, renamed, disabled, or failing during dependency import. A missing model more often disappears from a loader dropdown or triggers a model error during execution. Treat these as separate failure classes.

1. What can Install Missing in Manager fix?

ComfyUI-Manager’s Install Missing Custom Nodes primarily addresses missing node code. It installs nodes through the Registry or a source repository, but the following may still need separate work:

• Python dependencies used by the node, such as torch, numpy, or xformers in requirements.txt
• Model files, including checkpoints, VAEs, LoRAs, and ControlNets
• Custom model paths defined by a node’s own README

Comfy Desktop includes and enables Manager by default. In current Portable and Manual installations, the new Manager is built into ComfyUI core, but you must install manager_requirements.txt and launch with --enable-manager. If a node does not appear in Manager, it may not be registered, or a network problem may leave the list on cached or local data. Check the original repository before installing a similarly named package.

Use this order: look for Import failed in the console → search Manager or the Registry for the node → inspect the model path. For the full workflow-import process, see Reuse ComfyUI Workflows.

2. How to read Import failed

When the console reports Import failed, the last part of the traceback usually contains the missing module or conflicting version. Route the problem by error type:

Decision path:

1. ModuleNotFoundError: No module named 'xxx' → a Python package is missing

   • Do not install it into the system Python; install it into ComfyUI’s Python environment
   • Portable command: python_embeded\python.exe -m pip install -r custom_nodes\xxx\requirements.txt
   • Desktop and Manual paths differ, so identify the Python executable that ComfyUI actually uses

2. torch / CUDA / cuDNN errors → PyTorch and the GPU backend do not match

   • Check PyTorch: python -c "import torch; print(torch.__version__)"
   • Verify that the GPU driver meets the current system requirements
   • A node may require a torch version that conflicts with the version already used by ComfyUI

3. An exception inside the custom node → a node release or code defect

   • Search the node’s GitHub issues for the same traceback
   • If a new release caused the regression, test a known-good commit

Version-sensitive note: at packaging time, ComfyUI recommends Python 3.13, with 3.12 as a fallback when some custom-node dependencies fail on 3.13. PyTorch and CUDA requirements change quickly, so check the current system requirements.

3. Installed in Manager but still missing

When Manager shows a node as installed but it remains red after restart, or the console reports a torch/torchvision conflict, the installation state alone is not enough.

Why an installed node may still be unavailable:

• A network failure prevented the repository or dependencies from downloading completely
• The node’s Python requirements were not installed in ComfyUI’s environment
• The node is disabled or never imports successfully
• The node version is incompatible with the current ComfyUI version

Why dependencies conflict:

• Different custom nodes require different versions of torch, torchvision, or numpy
• A requirements.txt pins a strict version that conflicts with packages already installed

Resolution order:

1. Read the complete final traceback and classify it using the Import failed section
2. Disable or remove the conflicting node and check whether ComfyUI recovers
3. Inspect requirements.txt for strict pins such as torch==2.4.1
4. If the conflict remains, open an issue with:
   • The complete traceback
   • The result of python main.py --disable-all-custom-nodes
   • Python, PyTorch, and GPU driver versions

Version-sensitive note: Manager is transitioning between new, built-in, and legacy interfaces. Follow the current documentation for labels and menu locations. If the real problem is an OOM or VRAM peak, continue with ComfyUI Low-VRAM Optimization.

4. Model paths and missing dropdown entries

ComfyUI does not ship with model weights. Download checkpoints, VAEs, LoRAs, ControlNets, and upscalers separately and place them in the matching ComfyUI/models/ subfolder.

Check these in order when a file does not appear:

1. Correct directory

   • Put checkpoints in ComfyUI/models/checkpoints/
   • Put VAEs in ComfyUI/models/vae/
   • Put LoRAs, ControlNets, and upscalers in their matching type directories
   • A custom node may use a different directory; follow that project’s README

2. Restart or refresh

   • Restart ComfyUI or use the refresh mechanism supported by the current UI

3. File integrity

   • Compare the file size with the download source
   • Re-download or verify the file if it is incomplete

4. Compatible loader

   • Select a loader and workflow template built for that model type
   • FLUX, SD3.x, and other newer architectures may require specific text encoders, VAEs, and node combinations
   • Custom-node model paths can differ from the generic ComfyUI/models/ guidance

5. extra_model_paths.yaml

   • Portable and Manual installations can reference external model libraries through extra_model_paths.yaml; restart after saving it
   • Desktop uses its own extra-models configuration file; follow the current official path

For model and VAE pairing, see Stable Diffusion Model Selection.

Diagnose loading hangs with —disable-all-custom-nodes

When ComfyUI hangs on loading, opens to a blank page, or cannot render the UI, a custom-node frontend extension is a common cause. The --disable-all-custom-nodes flag quickly tells you whether custom nodes are involved.

1. Launch without custom nodes

Command:

python main.py --disable-all-custom-nodes

Windows Portable:

Copy run_nvidia_gpu.bat or run_cpu.bat, add --disable-all-custom-nodes to the launch command, and save it as a separate safe-start script.

Interpret the result:

• The problem disappears with custom nodes disabled → a custom node is responsible
  • Continue with a binary search
• The problem persists → custom nodes are not the source
  • Inspect ComfyUI core, system requirements, the GPU driver, and Python/PyTorch
  • Check model files and paths
  • Check for a VRAM peak with ComfyUI Low-VRAM Optimization

Version-sensitive note: confirm current launch flags with python main.py --help.

2. Isolate the bad node with a binary search

If the safe-start test proves that a custom node is responsible, a binary search narrows the set without guessing.

Principle: move or enable half of the custom nodes per test, observe the result, and repeatedly halve the suspect set.

Steps:

1. Back up ComfyUI/custom_nodes/
2. Move half of the node folders into a temporary test directory
3. Start ComfyUI and reproduce the problem
4. Interpret the result:
   • If the problem disappears → the bad node is in the half you moved
   • If it persists → the bad node is in the half that remains
5. Repeat until one node or a small interaction set remains

After locating the node:

• Search its GitHub issues for the same traceback
• Check requirements.txt for strict version pins
• Update, replace, disable, or remove the node
• If a new release caused the regression, test the previous known-good commit

Include this information in an issue:

• ComfyUI version
• Full error and reproduction steps
• Operating system
• Result of the --disable-all-custom-nodes test
• Python, PyTorch, GPU driver, and hardware details

Troubleshoot gray, black, or mismatched VAE output

Gray, white, tinted, or black output can come from a mismatched VAE, the wrong decode connection, VAE precision, attention precision, or a newer model that needs a different file and node combination. Test them in that order.

1. VAE troubleshooting order

Steps:

1. Verify the VAE connection

   • Connect the VAE from the checkpoint loader or a separate VAE loader to the decode node
   • Some checkpoints include a VAE; other models require a separate download

2. Match the VAE to the model and workflow

   • SD1.5, SDXL, FLUX, and SD3.x can require different VAE, text-encoder, and loader combinations
   • First run the smallest official workflow template or the model project’s README example

3. Check --fp16-vae

   • The official Startup Flags documentation notes that --fp16-vae may cause black images
   • Remove it, or test --fp32-vae / --bf16-vae if the hardware supports the alternative

4. Test precision flags

   • --fp32-vae: full-precision VAE, usually with higher VRAM use
   • --bf16-vae: BF16 VAE, requiring compatible hardware and backend support
   • --cpu-vae: run the VAE on the CPU, usually much slower
   • --force-upcast-attention: test whether attention upcasting fixes black output; it is not a general quality switch

5. Finally inspect VRAM, drivers, and dependencies

   • A VRAM peak can break VAE decoding
   • Confirm that the GPU driver meets current requirements
   • Confirm that PyTorch matches the GPU backend

Common symptoms:

Symptom	Possible cause
Gray, white, or tinted output	Wrong VAE, incorrect decode path, or workflow/model mismatch
Completely black output	--fp16-vae, attention precision, VRAM peak, or an invalid model combination
Load error	Damaged VAE, wrong path, or incomplete file set

2. Black-image risk with fp16 VAE

Many tutorials recommend --fp16-vae to reduce resource use, but the official Startup Flags reference explicitly warns that it may produce black images. Do not apply it without considering the model, hardware, and logs.

VAE precision flags:

Flag	Effect	When to consider it
--fp16-vae	Runs the VAE in FP16 and often reduces resource use	May cause black images; use carefully
--fp32-vae	Runs the VAE in full precision	Useful in black-image diagnosis, usually with higher VRAM use
--bf16-vae	Runs the VAE in BF16	Requires hardware and backend support
--cpu-vae	Runs the VAE on the CPU	A VRAM-constrained test path, usually slower

Attention precision:

• --force-upcast-attention: tests whether attention upcasting fixes black output
• --dont-upcast-attention: mutually exclusive with the previous flag and intended for debugging

Practical order:

• Do not copy a tutorial’s “speed flags” before reading the symptom and console output
• For black output, remove --fp16-vae first, then test --fp32-vae or --force-upcast-attention as appropriate
• Confirm flag names and defaults with the current python main.py --help
• For the full OOM and low-VRAM path, see ComfyUI Low-VRAM Optimization

3. Triage a VAE/model mismatch

When changing a model or VAE breaks an otherwise working workflow, the model, VAE, loader, or template probably does not match. Different model families require different file and node combinations.

What to verify by model family:

Model family	VAE check	Loader/workflow check
SD1.5 checkpoint	Use the built-in or a matching SD1.5 VAE	Start with an SD1.5-compatible base workflow
SDXL checkpoint	Use the built-in or a matching SDXL VAE	Use an SDXL-compatible template and loader
FLUX / SD3.x	Follow the model README for the VAE and text encoder	Follow the official template or project documentation

Diagnosis:

1. Check the model README, project page, or official template
   • Confirm whether the model includes a VAE, which companion weights it expects, and which loader it uses
2. Check the selected files in each loader
   • Confirm that the VAE in the dropdown matches the model and workflow
3. Reproduce with the smallest official template
   • Remove custom post-processing and reconnect nodes one at a time

Symptom mapping:

Symptom	Likely cause
Gray, white, or tinted output	Mismatched VAE, model, or decode path
Load error	Damaged VAE, wrong path, or incomplete file set
Minimal workflow works but the original does not	Post-processing or a custom node changes the decode path

For detailed model and VAE choices, see Stable Diffusion Model Selection.

Update strategy: stable, development, backup, and rollback

A ComfyUI update can break a workflow that worked yesterday. Development builds contain the newest commits and may include unresolved issues. Stable releases trade some recency for stability. A version record and rollback path are more useful than clicking every available update after the first failure.

1. Back up before choosing stable or development

Pre-update checklist:

1. Record the current ComfyUI commit

   • Git: git rev-parse HEAD
   • Portable or Desktop: record the version and update channel

2. Record Python and PyTorch

   • Python: python --version
   • PyTorch: python -c "import torch; print(torch.__version__)"
   • On NVIDIA systems, record the driver with nvidia-smi

3. Record important custom-node versions

   • Export or save the node list from Manager
   • Record commit hashes for production-critical nodes

4. Back up workflows and configuration

   • Export important workflow JSON files to a separate directory
   • Back up extra_model_paths.yaml, the Desktop extra-models config, and important user data

Stable vs Development:

Version type	Characteristics	Best fit
Stable / Release	Stabilized release that may lag in features	Production and long-lived environments
Development / Latest	Newest commits and earlier access to features	Testing new models, features, and node compatibility
Pinned commit	Fixed known state with no automatic later fixes	Temporary rollback, regression isolation, and reproduction

Update strategy by installation:

Installation	Strategy
Desktop	Defaults to a stable channel; use the current management UI to choose another channel when needed
Portable	update_comfyui_stable.bat follows stable; update_comfyui.bat follows development
Manual Git	Run git pull, then update requirements.txt inside the ComfyUI environment; switch commits to roll back

Version-sensitive note: confirm script names and Desktop settings in the current Update ComfyUI documentation.

2. Roll back after an update failure

First identify what changed: ComfyUI core, one custom node, or the Python environment.

Classify the change:

1. If only ComfyUI core was updated

   • Test whether the core starts with --disable-all-custom-nodes
   • Check whether custom nodes need compatible updates

2. If one custom node was updated

   • Return that node to the previous version
   • Or disable it and see whether ComfyUI recovers

3. If dependencies were updated

   • Recheck Python, PyTorch, and critical package versions
   • Portable’s update_comfyui_and_python_dependencies.bat reinstalls all dependencies; the official documentation warns that it can cause conflicts and break custom nodes pinned to particular package versions

Git rollback:

# Show recent commits
git log --oneline

# Switch to a known-good commit
git checkout <commit-hash>

# Update dependencies only inside the matching ComfyUI environment
pip install -r requirements.txt

Portable and Desktop rollback paths change over time. Prefer restoring the pre-update backup and follow the current update documentation. Do not uninstall first; doing so removes the version and configuration evidence needed to diagnose the regression.

Include this information in a custom-node issue:

• Full error and reproduction steps
• ComfyUI, Python, PyTorch, and GPU driver versions
• Result of the --disable-all-custom-nodes test
• Core or node versions before and after the update

Where to go next

Continue with the matching ComfyUI topic after the environment is stable:

1. Reproduce a shared workflow

   • Import a workflow, install its nodes and models, and connect its loaders
   • See Reuse ComfyUI Workflows

2. Reduce VRAM use

   • Continue from an OOM or VRAM peak into --lowvram, VAE, and model-quantization choices
   • See ComfyUI Low-VRAM Optimization

3. Upscale and inpaint

   • Restore workflows that use FaceDetailer, Impact Pack, or other post-processing nodes
   • See ComfyUI Upscaling and Inpainting

4. Generate video

   • Continue with video workflows, video VAEs, and last-step export problems
   • See ComfyUI Video Generation

5. Automate with the API

   • Work with API format, /prompt, node_errors, and queue management
   • See ComfyUI API Batch Automation

6. Choose models and VAEs

   • Compare checkpoints, VAEs, LoRAs, and loader configurations
   • See Stable Diffusion Model Selection