git:20260819.9fe9ea3 to git:20260825.ea35391

---

name: troubleshooting

globs:

- "**/*.json"

---

# ComfyUI Troubleshooting Guide

## Error Diagnosis Strategy

## 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

- High resolution images (2048x2048+)

- FP32 precision models on limited VRAM

- Video generation (LTXV, AnimateDiff) with many frames

- Large batch sizes

### Fixes (in order of preference)

- Search for FP8 variants: `download_model({ action: "search", query: "flux fp8" })` or the same with `"sdxl fp8"`

- Node: `VAEDecodeTiled` instead of `VAEDecode`

- Breaks the image into tiles, decodes each separately, and stitches them together

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

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

## 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

- Model offloading placed parts of the model on CPU

- A node produces CPU tensors while downstream expects GPU tensors

### Fixes

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

```

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

```

```

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

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

```

Import errors often reveal missing Python dependencies

```bash

pip install missing-package

```

## 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:

### Fixes

## 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

- Node: `VAELoader` with `vae-ft-mse-840000-ema-pruned.safetensors`

## CLIP Token Overflow

### Error Pattern

### 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

```

subject description, pose, clothing, setting

BREAK

lighting, style, quality, camera angle

```

## Black Images

### Error Pattern

### 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

- `CheckpointLoaderSimple` outputs: 0=MODEL, 1=CLIP, 2=VAE

- Getting index wrong: `["1", 0]` gives MODEL, `["1", 1]` gives CLIP

```

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

### Fixes

```

download_model({ action: "download", url: "...", target_subfolder: "checkpoints" })

```

## 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

```

get_system_stats() # Shows PyTorch version and CUDA version

```

## 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

## Error-Specific Debugging Commands

### Workflow Failed — Get Details

```

get_history(action="list") # Most recent execution

get_history(action="list", prompt_id="abc-123") # Specific execution

get_history(action="diagnose") # Why the last run failed

```

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

queue(action="list") # Running and pending jobs

get_system_stats (action:"logs")(max_lines=50, keyword="error") # Recent error logs

```

### Verify Node Availability

```

create_workflow(action="node_info", node_type="KSampler") # Check specific node

create_workflow(action="node_info", node_type="ControlNetApply") # Verify custom nodes loaded

```

### Verify Models

```

list_local_models({ action: "list", model_type: "checkpoints" }) # Installed checkpoints

list_local_models({ action: "list", model_type: "loras" }) # Installed LoRAs

list_local_models({ action: "list", 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 `create_workflow (action:"node_info")` |

## Sources

- **Official:** none found as a vendor error catalog. Launch-flag names cross-check against `comfyui-launch-flags` (upstream cli_args.py).

- **Empirical:** error→fix table from observed ComfyUI failures.