Skip to content

Troubleshooting Overview: When Something Goes Wrong, Check This Page First (60-Second Quick Check) ​

When ComfyUI throws an error, don't rush to search the error text. Most ComfyUI errors can be categorized within 60 seconds into four types: environment and startup, model loading, VRAM and generation, and custom nodes. This page helps you do a quick health check first, narrow the problem down to a category, and then jump to the corresponding dedicated page for in-depth handling.

What You'll Be Able to Do After Learning ​

  • Confirm whether your GPU, CUDA, and Python environment are working with 3 commands in 60 seconds
  • Categorize errors into "environment / model / VRAM / nodes" instead of searching blindly
  • Match against frequently seen error texts and directly apply verified solutions
  • Know what information to collect and where to ask when you can't solve it yourself

First Check: 60-Second Quick Check ​

The first thing to do when something goes wrong: go back to the terminal window where ComfyUI was launched and read the logs. When generation fails, the interface shows a "Prompt execution failed" dialog; click "Show report" to see the detailed error message—copy it first.

Then run these three commands in the terminal to check your environment:

bash
# 1. 确认 GPU 能被系统识别(NVIDIA 显卡)
nvidia-smi

# 2. 确认 PyTorch 的 CUDA 可用
python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

# 3. 确认 Python 版本(需 3.9+,推荐 3.12)
python --version

You should see: command 1 lists the GPU model and driver version; command 2 outputs CUDA available: True; command 3 outputs a version number of 3.9 or higher. If any of these doesn't match expectations, jump to What to Do If It Won't Install: Installation and Startup Troubleshooting first.

💡 Rule out custom nodes first

Among the feedback issues received by the official team, most are related to custom nodes. Before digging deeper, first disable all custom nodes following the method in Custom Node Troubleshooting: Disable First, Then Bisect to confirm whether the problem is caused by nodes.

Common Issue Troubleshooting ​

Environment and Startup ComfyUI Errors ​

"Torch not compiled with CUDA enabled" ​

Cause: The installed PyTorch is the CPU version without compiled CUDA support, so the GPU cannot participate in computation.

Solution:

  1. First uninstall the existing torch:
bash
pip uninstall torch
  1. Reinstall the CUDA version of PyTorch (CUDA 13.0):
bash
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
  1. Verify the installation:
bash
python -c "import torch; print(torch.cuda.is_available())"

You should see: the output True.

"Frontend or Templates Package Not Updated" ​

Cause: After updating ComfyUI via Git, the frontend dependencies were not updated in sync.

Solution:

bash
pip install -r requirements.txt

You should see: after the dependencies finish installing, restart ComfyUI and the message disappears.

Model Loading Issues ​

"Value not in list: ckpt_name: 'model-name.safetensors' not in []" ​

Cause: The model file referenced by the workflow doesn't exist—either it wasn't downloaded, or it's in the wrong subdirectory. An empty list with not in [] means ComfyUI didn't find a single model in the corresponding directory.

Solution:

  1. Check that the model is in the correct subdirectory:
    • Checkpoints:models/checkpoints/
    • VAE:models/vae/
    • LoRA:models/loras/
    • ControlNet:models/controlnet/
  2. If the model is missing, use ComfyUI Manager to download it automatically, or download it manually and put it in the corresponding directory.
  3. If the model is stored elsewhere (for example, shared with other painting software), edit extra_model_paths.yaml to add custom model directories; see Windows Portable Package Installation.

You should see: after restarting ComfyUI, the model appears in the node's dropdown list.

"Error while deserializing header" ​

Cause: The model file was corrupted during download, or it can't be read due to insufficient disk space or incorrect file permissions.

Solution:

  1. Re-download the model (model files can be 2–15GB or larger, make sure the download completes).
  2. Check that there is enough free disk space.
  3. Check that the ComfyUI process has read permission for the model file.
  4. Test with a different model to determine whether it's a single-file issue or a systemic one.

VRAM and Generation ComfyUI Errors ​

"RuntimeError: CUDA out of memory" ​

Cause: There isn't enough VRAM to hold the current model and workflow, common with large models or high-resolution generation.

Solution: Gradually reduce VRAM usage in order, restarting ComfyUI after each change:

bash
# 方案 1:先用 lowvram(文本编码器放到 CPU)
python main.py --lowvram

# 方案 2:不够再换 novram
python main.py --novram

# 方案 3:最后手段,纯 CPU(很慢,仅绝对必要时使用)
python main.py --cpu

You can also lower the generation resolution or batch size, and close other programs that use VRAM. For more systematic solutions, see Insufficient VRAM and Stuttering: Systematic Solutions for OOM.

You should see: generation runs to completion without being interrupted by errors.

"Generation output is all black or a solid color" ​

Cause: Something went wrong in the output stage. Documented causes include: VAE stage issues (the default text-to-image pipeline is KSampler → VAE Decode → Save Image, and an incorrectly loaded VAE directly affects the output); the --fp16-vae startup flag runs the VAE in fp16, which may cause black images; on quantized models, the attention backend may silently return black output.

Solution:

  1. Check the workflow: confirm that VAE Decode comes after KSampler, and that the loaded VAE matches the model architecture (for example, Flux requires ae.safetensors, not sdxl_vae or taesd).
  2. If --fp16-vae was added at startup, remove that flag and restart.
  3. If FlashAttention is enabled (via --use-flash-attention or a node pack), switch to the default attention backend, restart, and try again—disabling FlashAttention on quantized models has been verified to fix all-black output.
  4. Turn off live preview to rule out interference: in some cases only the preview is black while the saved file is actually fine.

You should see: after regenerating, the output is a normal image.

Custom Node Issues ​

"Can't Find Custom Node" ​

Cause: The custom node used by the workflow is not installed or not properly enabled, and the frontend validation reports an error.

Solution:

  1. First temporarily disable node validation in ComfyUI settings to determine the scope of the problem.
  2. Install the corresponding node pack as prompted and restart.
  3. If the problem persists, follow the process in Custom Node Troubleshooting: Disable First, Then Bisect to disable all nodes and then bisect to locate the issue.

"Missing nodes still showing as missing after installation and restart" ​

Cause: The node is wrapped but its dependency import failed — you'll often see “Failed to import” in the console/logs. Typical causes: the node package requires extra wheel dependencies; different plugins have conflicting dependency version requirements (e.g., one needs torch==2.4.1 while another needs torch>=2.4.2); network issues prevented dependencies from being installed.

Solution:

  1. Open the terminal log and find the node package name associated with “Failed to import”.
  2. Manually install the missing dependencies for that node package.
  3. If there is a dependency version conflict, handle it using the Python environment management methods on the custom node troubleshooting page.

Still not working? ​

Gathering this information before asking a question can greatly improve resolution efficiency:

bash
# GPU 型号与驱动版本
nvidia-smi --query-gpu=driver_version --format=csv

# CUDA 是否可用及版本
python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"

# Python 版本
python --version

When asking, include: the complete original error text (terminal log or “Show report” contents), GPU model, ComfyUI version, installation method (desktop / portable / manual install), and whether custom nodes are used.

Where to ask:

Next Lesson Preview ​

This page helps you categorize ComfyUI errors into four major types. The next lesson dives into the most frequent type: Custom Node Troubleshooting: Disable First, Then Bisect, teaching you to use bisection to quickly pinpoint the offending node.

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.