Debugging

Practical pointers for diagnosing common failures in the codebase.

Logging

Logging is configured by modules/logging_config.py, which honours --loglevel and an SD_WEBUI_LOG_LEVEL env var. Defaults are:

• Root logger: WARNING
• modules.* loggers: INFO
• Errors caught by errors.report() (modules/errors.py) are printed with a coloured "***" header followed by a Python traceback.

Set --loglevel DEBUG for verbose output. Several module-level prints (notably checkpoint loading and extension scanning) bypass logging and write to stdout.

Boot fails before the UI loads

Most early failures happen in modules/launch_utils.py:

Symptom	Cause	Fix
Couldn't launch python	python_cmd not on PATH	Set python_cmd= in webui-user.sh
Pip install hangs / fails	Network / mirror issues	Use --skip-install after the first install
Cannot find checkpoint	No .safetensors in models/Stable-diffusion/	Pass --ckpt path/to/file.safetensors or download a model
RuntimeError: Torch is not able to use GPU	CUDA not available	Add --skip-torch-cuda-test to bypass; --use-cpu all to actually run on CPU
Could not parse extension metadata.ini	Malformed extension	Disable the extension (--disable-all-extensions) and inspect

The startup timer printed at the end of the boot tells you which phase took the longest. If it's the "scripts" phase, an extension is slow; if it's load_model_weights, the checkpoint is being scanned/hashed.

NaN / black images

Black images are the #1 user complaint. The relevant code is test_for_nans() in modules/devices.py; it raises NansException when the model output is all nan or inf. Common causes:

• The checkpoint expects fp32 but --no-half was not set. Add --no-half and retry.
• The VAE has been swapped to one incompatible with the model. Check the VAE dropdown in Settings.
• Some 1.5-derived models produce NaNs on Apple Silicon (MPS). modules/mac_specific.py has workarounds; verify it's being applied.

You can disable the check with --disable-nan-check to see what comes out, but the underlying issue is real and the result will be unusable.

Out-of-memory errors

Common patterns and the corresponding flag/option to try:

Error	Try
CUDA out of memory during UNet	--medvram (8 GB cards) or --lowvram (4 GB)
OOM only when applying Lora	Reduce the number of Loras in the prompt
OOM during VAE decode	--no-half-vae; or use TAESD via Settings → "VAE Approx"
OOM on hires fix	Lower the upscale factor or use a tile-based upscaler (ESRGAN/SwinIR) instead of latent
RAM (not VRAM) OOM at startup	--lowram to load weights to VRAM rather than RAM

The MEM monitor in modules/memmon.py reports peak memory after each generation in the log; check that against your device limits.

Extension misbehaves

To isolate whether an extension is the culprit:

# Disable all extensions, including built-in ones
python launch.py --disable-all-extensions

# Or only third-party extensions, keeping built-ins like Lora
python launch.py --disable-extra-extensions

If the bug disappears, bisect by re-enabling extensions one at a time. The console will print which extension's process() callback is currently running because of report_exception() in modules/script_callbacks.py; look for Error executing callback ... for /path/to/extension/scripts/foo.py.

sysinfo dumps

For bug reports, the project provides:

python launch.py --dump-sysinfo

This writes a JSON file with installed package versions, command-line args, runtime info, and (sanitised) settings, then exits. The same file can be downloaded from Settings → Show System Info → "Download".

The sysinfo serialiser is in modules/sysinfo.py; it explicitly redacts paths under the user's home dir.

Profiling a slow generation

v1.8 added a built-in PyTorch profiler. Toggle "Run torch profiler for image generation" in Settings → System (the option key is profile_torch). On the next generation, a trace.json is written to the output directory; load it with chrome://tracing/ or https://ui.perfetto.dev/. The integration lives in modules/profiling.py.

For extension performance, the startup timer can be repurposed: extensions can use with shared.timer.subcategory("my work"): to record durations that show up in the startup summary and the /sdapi/v1/system-info response.

Frontend (browser-side) debugging

The Gradio app loads JavaScript from script.js and the entire javascript/ directory. Useful tactics:

• Open DevTools and run gradioApp().querySelector('#tab_txt2img') to inspect a tab's DOM. gradioApp() is provided by script.js and unwraps Gradio's shadow DOM.
• The notifications.js and progressbar.js modules log errors to the browser console.
• Pass --gradio-debug to make Gradio print every event to the server console.
• For CSS issues, inspect style.css — there is no source map and no preprocessor, so the file you see is the file that's served.

When in doubt

Settings → "Show all pages" makes every available setting visible. Extensions sometimes register options that are only shown when their tab is also visible.