---
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 (`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`](../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 simultaneously — 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/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–32GB):** `--gpu-only --use-sage-attention --cache-classic`
- **12–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 being combined with a tensor on the GPU. This usually happens when:
- A custom node doesn't properly 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("NodeClassName")
   ```
2. **Install via ComfyUI Manager** or the registry
3. **Check logs for import errors**:
   ```
   get_logs(keyword="import")
   get_logs(keyword="error")
   ```
   Import errors often reveal missing Python dependencies
4. **Install missing Python dependencies**: If the custom node requires a pip package:
   ```bash
   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**: Ensure the LoRA matches 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**: `--force-fp32` flag forces everything to FP32 (uses more VRAM)

## CLIP Token Overflow

### Error Pattern

No explicit error — the prompt is silently truncated at 77 tokens, 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

### Fixes

1. **Use BREAK token**: Split the prompt at natural boundaries:
   ```
   subject description, pose, clothing, setting
   BREAK
   lighting, style, quality, camera angle
   ```
2. **Use CLIPTextEncodeSDXL**: SDXL's dual-CLIP processes two 77-token chunks
3. **Prioritize important tokens**: Put the most important descriptors first
4. **Use fewer filler words**: Remove articles and prepositions where possible
5. **Use embeddings**: Condense complex concepts into single tokens with textual inversions

## Black Images

### Error Pattern

No error in the execution — the workflow "succeeds" but produces completely black or near-black images.

### Root Causes and Fixes

| Cause | Diagnosis | Fix |
|-------|-----------|-----|
| `denoise = 0` | Check KSampler inputs | Set denoise to 1.0 for txt2img, 0.5-0.8 for img2img |
| `cfg = 0` | Check KSampler inputs | Set CFG to 7.0 (SD 1.5), 1.0 (Flux) |
| `steps = 0` | Check KSampler inputs | Set steps to 20+ (standard) or 4+ (turbo) |
| Wrong VAE | VAE doesn't match model | Use the correct VAE for the model family |
| Empty prompt | CLIPTextEncode has empty text | Add a text prompt |
| Wrong scheduler | Incompatible scheduler/sampler combo | Try `"normal"` scheduler with `"euler"` sampler |
| Seed collision | Extremely rare | Change the seed value |
| FP16 VAE overflow | VAE decode produces black | Use FP32 VAE or VAEDecodeTiled |

### Quick Diagnostic Checklist

1. Check `denoise` > 0 (should be 1.0 for txt2img)
2. Check `cfg` > 0 (should be 7.0 for SD 1.5, 1.0 for Flux)
3. Check `steps` > 0 (should be 20 for standard, 4 for turbo)
4. Verify the positive prompt is not empty
5. Try a different seed
6. Try a known-working sampler/scheduler combo: `euler` + `normal`

## Connection Type Errors

### Error Pattern

```
Output type 'IMAGE' doesn't match input type 'LATENT'
```

Or:

```
Required input 'model' of type 'MODEL' but got connection of type 'CLIP'
```

### Root Cause

Connecting the wrong output slot of a node to an incompatible input. Often caused by using the wrong output index.

### Fixes

1. **Check output indices**: Use `get_node_info` to verify the exact output order
   - `CheckpointLoaderSimple` outputs: 0=MODEL, 1=CLIP, 2=VAE
   - Getting index wrong: `["1", 0]` gives MODEL, `["1", 1]` gives CLIP
2. **Verify connection format**: `["nodeId", outputIndex]` — node ID is a string, index is an integer
3. **Check data type flow**: Ensure the pipeline follows the correct type chain:
   ```
   MODEL → KSampler
   CLIP → CLIPTextEncode → CONDITIONING → KSampler
   LATENT → KSampler → LATENT → VAEDecode → IMAGE
   VAE → VAEDecode, VAEEncode
   ```

## Model Loading Errors

### Error Pattern

```
FileNotFoundError: [Errno 2] No such file or directory: 'models/checkpoints/model.safetensors'
```

Or:

```
SafetensorError: Error reading file: invalid header
```

Or:

```
RuntimeError: PytorchStreamReader failed reading zip archive
```

### Root Causes

- **File not found**: Model file doesn't exist at the referenced path
- **Corrupted download**: Incomplete or damaged file
- **Wrong format**: File is not a valid safetensors/pickle/checkpoint format

### Fixes

1. **Verify the model exists**: `list_local_models(model_type="checkpoints")`
2. **Check the exact filename**: Model names in workflows must match the filename exactly (case-sensitive)
3. **Re-download**: If hash mismatch or corruption:
   ```
   download_model(url="...", target_subfolder="checkpoints")
   ```
4. **Check file size**: A 1KB safetensors file is clearly corrupted — re-download
5. **Verify subfolder**: Models must be in the correct subfolder (`checkpoints/`, `loras/`, `vae/`, etc.)

## Torch / CUDA Version Errors

### Error Pattern

```
RuntimeError: CUDA error: no kernel image is available for execution on the device
```

Or:

```
ImportError: cannot import name 'xxx' from 'torch'
```

Or:

```
AssertionError: Torch not compiled with CUDA enabled
```

### Root Cause

PyTorch and CUDA version incompatibility, usually after:
- Updating PyTorch without matching CUDA toolkit
- Installing a custom node that downgrades/changes PyTorch
- Using pip install that pulls a CPU-only PyTorch

### Fixes

1. **Check current versions**:
   ```
   get_system_stats()  # Shows PyTorch version and CUDA version
   ```
2. **Verify CUDA availability**: In Python: `torch.cuda.is_available()`
3. **Reinstall PyTorch with CUDA**: Visit pytorch.org for the correct install command matching your CUDA version
4. **Pin PyTorch version**: After fixing, avoid running `pip install` commands that might change PyTorch
5. **Use ComfyUI's bundled venv**: ComfyUI Desktop ships with a pre-configured Python environment

## ComfyUI Desktop vs CLI Differences

### Key Differences

| Aspect | ComfyUI Desktop | ComfyUI CLI |
|--------|----------------|-------------|
| Default port | 8000 | 8188 |
| Python | Embedded (bundled) | System/venv Python |
| Install location | `AppData/Local/Programs/ComfyUI/` | Wherever you cloned it |
| Custom nodes | `Documents/ComfyUI/custom_nodes/` | `./custom_nodes/` in repo |
| Models | `Documents/ComfyUI/models/` | `./models/` in repo |
| Config | `extra_model_paths.yaml` for shared paths | Same |
| Updates | Auto-updater in the app | `git pull` |

### Common Issues

- **Wrong port**: MCP tools default to 8188 — if using Desktop, configure for port 8000
- **Path confusion**: Desktop separates user data from application files
- **Custom node pip installs**: Desktop's embedded Python may not be on PATH — install within the venv

## Error-Specific Debugging Commands

### Workflow Failed — Get Details

```
get_history()                           # Most recent execution
get_history(prompt_id="abc-123")        # Specific execution
```

The response includes:
- `status.status_str`: "success" or "error"
- `status.messages`: Timestamped execution messages
- `outputs`: Node outputs (images, etc.)
- Error traceback for failed nodes

### Check Server Health

```
get_system_stats()    # GPU info, VRAM, Python/PyTorch versions
get_queue()           # Running and pending jobs
get_logs(max_lines=50, keyword="error")  # Recent error logs
```

### Verify Node Availability

```
get_node_info(node_type="KSampler")              # Check specific node
get_node_info(node_type="ControlNetApply")        # Verify custom nodes loaded
```

### Verify Models

```
list_local_models(model_type="checkpoints")       # Installed checkpoints
list_local_models(model_type="loras")             # Installed LoRAs
list_local_models(model_type="controlnet")        # Installed ControlNets
```

## Quick Reference: Error to Fix

| Error Message (partial) | Most Likely Fix |
|--------------------------|----------------|
| `CUDA out of memory` | Reduce resolution, use FP8 model; VRAM ladder `--lowvram` → `--novram --cache-none` → `--reserve-vram N` ([launch flags](../comfyui-launch-flags/SKILL.md)) |
| `Expected all tensors on same device` | Update custom node, restart ComfyUI |
| `Cannot find node class` | Install the node pack, restart ComfyUI |
| `Input contains NaN` | Lower CFG, use FP32 VAE, remove LoRAs |
| `expected scalar type Float but found Half` | Use FP32 VAE, or `--force-fp32` |
| `No such file or directory` (model) | Check filename, re-download model |
| `invalid header` (safetensors) | Re-download — file is corrupted |
| `CUDA error: no kernel image` | Reinstall PyTorch with matching CUDA version |
| Black images, no error | Check denoise > 0, cfg > 0, steps > 0, prompt not empty |
| Image looks garbled/noisy | Wrong model+VAE combo, wrong sampler settings |
| `Connection refused` on port 8188 | ComfyUI not running, or using Desktop (port 8000) |
| `Prompt outputs failed validation` | Node inputs don't match schema — check `get_node_info` |