/troubleshooting

name: troubleshooting
description: Common ComfyUI errors and fixes. OOM, missing nodes, dtype mismatches, black images, and debugging strategies
globs:
  - "**/*.json"

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`](../comfyui-launch-flags/SKILL.md)

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

| Model | FP32 | FP16 | FP8 | |-------|------|------|-----| | SD 1.5 | ~4GB | ~2GB | ~1GB | | SDXL | ~12GB | ~6GB | ~3GB | | Flux Dev | ~48GB | ~24GB | ~12GB | | Flux Schnell | ~48GB | ~24GB | ~12GB | | LTXV | ~20GB+ | ~10GB+ | ~6GB |

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)

| Flag | Card | Behavior | |------|------|----------| | `--gpu-only` | 16GB+ | Everything (CLIP/VAE/UNet) stays on GPU — fastest, max VRAM | | `--highvram` | 12–16GB | Models stay resident in GPU after use, no CPU offload | | `--normalvram` | 8–12GB | Default balance — unload to CPU RAM when idle | | `--lowvram` | 6–8GB | Split the UNet, aggressive CPU offload — slower | | `--novram` | 4–6GB | Extreme split/offload — for OOM even on lowvram, or long videos | | `--cpu` | <4GB / no GPU | CPU only (very slow) |

`--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)

| Flag | Effect | |------|--------| | `--cache-classic` | Default aggressive caching (fastest re-runs, most RAM) | | `--cache-lru N` | Keep the last N node results (bounded RAM) | | `--cache-ram N` | Cap cache to N GB of headroom | | `--cache-none` | No caching — minimal RAM, re-runs every node |

Attention (speed vs compatibility)

| Flag | Notes | |------|-------| | `--use-sage-attention` | **Recommended** — fast + efficient (needs SageAttention + Triton; see `triton-sageattention`) | | `--use-flash-attention` | Very fast on supported GPUs | | `--use-pytorch-cross-attention` | PyTorch 2.x native — best compatibility | | `--use-split-cross-attention` | Lower VRAM, slower | | `--use-quad-cross-attention` | Sub-quadratic optimization | | (omit) | Auto-selects xFormers if available |

Precision (UNet)

| Flag | Effect | |------|--------| | `--fp16-unet` | Half precision, ~50% VRAM | | `--bf16-unet` | BFloat16, good balance (newer GPUs) | | `--fp8_e4m3fn-unet` | 8-bit float, max savings (newest GPUs) |

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 -