Debugging

Practical playbook for diagnosing problems while working on ComfyUI.

Logs

Logging is configured by app/logger.py via setup_logger(log_level=args.verbose, use_stdout=args.log_stdout). The default level is INFO; --verbose DEBUG turns on noisy logs from model loading, memory management, and the prompt executor.

Logs are also accessible programmatically:

• GET /internal/logs — concatenated log text
• GET /internal/logs/raw — structured entries
• PATCH /internal/logs/subscribe — stream logs over WebSocket

These routes are defined in api_server/routes/internal/internal_routes.py.

Common errors

"CUDA error" / OOM

• Try --lowvram or --novram.
• Try --disable-cuda-malloc if the device is on the cudaMallocAsync blacklist (printed as a warning at startup; see cuda_malloc_warning in main.py).
• Try a smaller batch size or lower-resolution latent.
• For Flux/HunyuanVideo-class models, try --fp8_e4m3fn-unet.

"Torch not compiled with CUDA enabled"

Reinstall the right wheel — see the README's per-vendor sections.

Black images / NaN latents

• Try --fp32-vae or --bf16-vae.
• Try --force-upcast-attention.

"Database is locked"

Two ComfyUI processes are using the same SQLite file. Either stop the other instance or pass --database-url sqlite:///path/to/another.db. The lockfile is acquired in _acquire_file_lock in app/database/db.py.

Custom nodes not loading

• Check the startup log. nodes.init_extra_nodes logs each custom node import and any errors.
• Try --disable-all-custom-nodes to confirm the issue is in a custom node.
• Look for prestartup_script.py files in custom_nodes/*/ that might be erroring before the main import.

"WARNING: Potential Error in code: Torch already imported"

Something imported torch before main.py configured device env vars (CUDA_VISIBLE_DEVICES, TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL, etc.). Trace what you imported at the top of main.py or before; only comfy.options, os, importlib, folder_paths, and a handful of pure-Python helpers should run before torch.

Faulthandler

main.py calls faulthandler.enable(file=sys.stderr, all_threads=False) so segfaults produce a Python traceback. If a CUDA crash kills the process silently, that's where the missing crash log usually shows up.

Hook restoration

If you suspect a custom node has monkey-patched a core function and not restored it, see hook_breaker_ac10a0.py. main.py calls save_functions() before initializing extra nodes and restore_functions() between executions to keep core state clean.

Slow startup

Startup time is dominated by:

1. Custom-node imports (nodes.init_extra_nodes).
2. Frontend bundle resolution (app/frontend_management.py).
3. Database migrations (app/database/db.py) when the schema is out of date.
4. Asset scanner if --enable-assets is on (it runs in the background but does an initial walk).

Each of these logs timing. Pass --verbose DEBUG to see them.

Reproducing a workflow

A queued prompt gets a prompt_id (UUID). It threads through /history/<prompt_id> so you can fetch the exact graph and outputs after the fact. The frontend also lets you drag the saved PNG/WebP/FLAC back onto the canvas to recover the workflow that produced it — this works because server.py embeds the prompt JSON in the file's metadata when --disable-metadata is not set.