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 (read_skill("debug-render")): 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/missing node.

Error Diagnosis Strategy

When a workflow fails, follow this systematic approach:

1. Get the error: Use get_history to retrieve the execution result with full traceback
2. Check logs: Use get_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 get_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 simultaneously. Common triggers:

• High resolution images (2048x2048+)
• Multiple models loaded simultaneously
• 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: search_models("flux fp8") or search_models("sdxl fp8")
3. Launch flags (the VRAM ladder): offload aggressively via ComfyUI CLI flags —
   • --lowvram — offload text encoders / model parts to CPU
   • --novram — extreme offload; the go-to for long video (LTX 2 / WAN) OOM
   • --cache-none — cache nothing (lowest RAM/VRAM); combine with --novram
   • --reserve-vram N — reserve N GB so the GPU stops spilling into slow shared VRAM (Windows); typical 2–4
   • --disable-smart-memory — force offload to RAM when a run gets stuck / intermittently OOMs
   • Full matrix + 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 simultaneously — use one checkpoint and LoRAs instead
8. For LTXV/video: Always use FP8 quantized video models on 24GB cards