Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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_runto_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:
Get the error. Use get_history(action="diagnose") to retrieve the execution result with the full traceback, plus any missing models/nodes
Check logs. Use get_system_stats (action:"logs") with keyword filters like "error", "warning", "traceback"
Identify the failing node. The history response includes the node_id and node_type that failed
Cross-reference inputs. Use create_workflow (action:"node_info") to verify the failing node's expected input schema
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)
Reduce resolution. Drop to the model's native resolution (512 for SD 1.5, 1024 for SDXL/Flux)
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"
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
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)
Check file size. A 1KB safetensors file is corrupted; re-download
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
Check current versions:
get_system_stats() # Shows PyTorch version and CUDA version
Verify CUDA availability. In Python: torch.cuda.is_available()
Reinstall PyTorch with CUDA. Visit pytorch.org for the correct install command matching your CUDA version
Pin PyTorch version. After fixing, avoid running pip install commands that might change PyTorch
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(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
