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