Troubleshooting

ComfyUI Troubleshooting Guide

Render completes but looks WRONG (artifacts, wrong subject/pose/color, a ControlNet/mask/LoRA not taking, a refiner degrading it)? That's not an error. Use the debug-render skill (list_packs with action: "skill_read", name: "debug-render") to localize the bad stage with run-to-node (panel_run to_node_id) by previewing intermediate steps. This guide is for runs that fail with an error, OOM, or missing node.

Error Diagnosis Strategy

When a workflow fails, follow this approach:

1. Get the error. Use get_history(action="diagnose") to retrieve the execution result with the full traceback, plus any missing models/nodes
2. Check logs. Use get_system_stats (action:"logs") with keyword filters like "error", "warning", "traceback"
3. Identify the failing node. The history response includes the node_id and node_type that failed
4. Cross-reference inputs. Use create_workflow (action:"node_info") to verify the failing node's expected input schema
5. Check models. Use list_local_models to verify all referenced model files exist

Out of Memory (OOM)

Error Pattern

torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate X MiB.
GPU 0 has a total capacity of 24.00 GiB of which X MiB is free.

Or:

RuntimeError: CUDA error: out of memory

Root Cause

The GPU does not have enough VRAM to hold the model weights, intermediate tensors, and latent images at the same time. Common triggers:

• High resolution images (2048x2048+)
• Multiple models loaded at the same time
• FP32 precision models on limited VRAM
• Video generation (LTXV, AnimateDiff) with many frames
• Large batch sizes

Fixes (in order of preference)

1. Reduce resolution. Drop to the model's native resolution (512 for SD 1.5, 1024 for SDXL/Flux)
2. Use FP8/FP16 quantized models. FP8 Flux models use ~8GB vs ~24GB for FP16
   • Search for FP8 variants: download_model({ action: "search", query: "flux fp8" }) or the same with "sdxl fp8"
3. Launch flags (the VRAM ladder). Offload via ComfyUI CLI flags:
   • --lowvram offloads text encoders / model parts to CPU
   • --novram is extreme offload, the go-to for long video (LTX 2 / WAN) OOM
   • --cache-none caches nothing (lowest RAM/VRAM); combine with --novram
   • --reserve-vram N reserves N GB so the GPU stops spilling into slow shared VRAM (Windows); typical 2 to 4
   • --disable-smart-memory forces offload to RAM when a run gets stuck or OOMs intermittently
   • Full matrix and recipes: comfyui-launch-flags
4. Free VRAM between generations. ComfyUI should auto-manage, but restarting clears leaked memory
5. Use tiled VAE decoding. For high-resolution images, tile the VAE decode step
   • Node: VAEDecodeTiled instead of VAEDecode
   • Breaks the image into tiles, decodes each separately, and stitches them together
6. Reduce batch size. Set batch_size to 1 in EmptyLatentImage
7. Avoid multiple models. Don't load two full checkpoints at the same time; use one checkpoint and LoRAs instead
8. For LTXV/video: always use FP8 quantized video models on 24GB cards

VRAM Estimates

Launch Flags — VRAM / Cache / Attention / Precision

ComfyUI's startup flags tune the speed↔VRAM tradeoff. Match them to the detected GPU (the panel orchestrator reports VRAM/GPU/torch/sage in its env block; pick the tier from there). Set them on the process that launches ComfyUI (or the --panel-orchestrator / connect command's ComfyUI, not the agent).

VRAM mode (pick ONE by card size)

--reserve-vram N (GB) leaves headroom for the OS and other apps. Bump it if you OOM intermittently mid-run (VAE decode / audio round-trips spike).

Cache (RAM vs re-run speed)

Attention (speed vs compatibility)

Precision (UNet)

Typical recipes:

• RTX 4090/5090 (24 to 32GB): --gpu-only --use-sage-attention --cache-classic
• 12 to 16GB: --highvram --use-sage-attention (or --fp8_e4m3fn-unet for big models)
• 8GB: --normalvram --use-sage-attention --cache-lru 20
• 6GB: --lowvram --use-split-cross-attention --cache-none
• OOM on long video: --novram --reserve-vram 2

Device Mismatch

Error Pattern

RuntimeError: Expected all tensors to be on the same device, but found at least
two devices, cuda:0 and cpu!

Root Cause

A tensor on the CPU is combined with a tensor on the GPU. This usually happens when:

• A custom node doesn't move tensors to the correct device
• Model offloading placed parts of the model on CPU
• A node produces CPU tensors while downstream expects GPU tensors

Fixes

1. Check if the error occurs with a specific custom node. Update or replace that node
2. If using --lowvram or --cpu, some nodes may not support CPU offloading
3. Restart ComfyUI to reset device state
4. Check if a custom node has a newer version that fixes device handling

Missing Nodes

Error Pattern

Cannot find node class 'NodeClassName'

Or in the execution response:

"error": {"type": "node_not_found", "message": "Cannot find node class 'X'"}

Root Cause

The workflow references a node type that is not installed. This happens when:

• A custom node pack is not installed
• A custom node pack is installed but failed to load (import error)
• The node was renamed or removed in a pack update

Fixes

1. Search for the node pack:

   search_custom_nodes(action="search", query="NodeClassName")

2. Install via ComfyUI Manager or the registry
3. Check logs for import errors:

   get_system_stats (action:"logs")(keyword="import")
   get_system_stats (action:"logs")(keyword="error")

   Import errors often reveal missing Python dependencies
4. Install missing Python dependencies. If the custom node requires a pip package:

   pip install missing-package

5. Restart ComfyUI after installing any custom node. Nodes are loaded at startup

NaN Tensor Errors

Error Pattern

RuntimeError: Input contains NaN

Or images come out as solid gray/noise with NaN warnings in logs.

Root Cause

Numerical instability during the diffusion process. Common triggers:

• CFG scale too high. Values above 15-20 can cause numerical overflow
• Corrupted model weights. Damaged download or incompatible merge
• FP16 overflow. Some operations overflow at half precision
• Incompatible LoRA. A LoRA trained for a different base model

Fixes

1. Lower CFG. Try CFG 7.0 for SD 1.5/SDXL, 1.0 for Flux
2. Use FP32 VAE. Some VAEs produce NaN in FP16. Switch to vae-ft-mse-840000-ema-pruned.safetensors (FP32)
3. Remove LoRAs. Test without LoRAs to isolate the cause
4. Re-download the model. Hash verification can detect corrupted files
5. Check LoRA compatibility. The LoRA must match the base model family

Dtype Mismatches

Error Pattern

RuntimeError: expected scalar type Float but found Half

Or:

RuntimeError: expected scalar type Half but found Float

Or:

RuntimeError: Input type (float) and bias type (c10::Half) should be the same

Root Cause

A model component expects one precision (FP32/FP16) but receives another. Most common with:

• VAE precision mismatch (FP16 model + FP32 VAE or vice versa)
• Mixed-precision LoRAs
• Custom nodes that force a specific dtype

Fixes

1. Use a separate VAE. Load an explicit FP32 VAE instead of the checkpoint's built-in VAE
   • Node: VAELoader with vae-ft-mse-840000-ema-pruned.safetensors
2. Match precision. If the model is FP16, use FP16-compatible nodes throughout
3. Force FP32 VAE decode. Some node packs offer VAEDecodeFP32 nodes
4. Check ComfyUI settings. The --force-fp32 flag forces everything to FP32 (uses more VRAM)

CLIP Token Overflow

Error Pattern

No explicit error. The prompt is truncated at 77 tokens without warning, and details mentioned late in the prompt are ignored.

Symptoms

• Later parts of long prompts have no effect on the image
• Adding more descriptive text doesn't change the output
• Removing early tokens suddenly makes later tokens work