Debug

To run SD.Next in debug mode, start it with the --debug flag. This has negligible overhead and is safe for daily use. It adds more detail to logs.

Example:

webui.bat --debug
webui.sh --debug

Extra Debug

Some debug output is too verbose for regular use, so it is controlled through environment variables.

Install & load

SD_INSTALL_DEBUG: report detailed information related to packages installation
SD_PATH_DEBUG: report all used paths as they are parsed
SD_SCRIPT_DEBUG: increase verbosity of script and extension load and execution
SD_MOVE_DEBUG: trace all model moves from and to cpu/gpu
SD_EXT_DEBUG: trace extensions load/install/update operations
SD_LOAD_DEBUG: report all model loading operations as they happen
SD_PIP_DEBUG: report details about all pip operations
SD_CONFIG_DEBUG: report all configuration processing requests
SD_ENV_DEBUG: trace environment detection and startup behavior
SD_PLATFORM_DEBUG: trace platform/device initialization
SD_TORCH_DEBUG: trace PyTorch internal initialization
SD_TRANSFORMERS_DEBUG: trace Transformers internal operations
SD_QUEUE_DEBUG: debug request queue behavior
SD_METADATA_DEBUG: trace image metadata read/write operations
SD_MOVE_VERBOSE: print more verbose model move information
SD_COMPILE_DEBUG: trace model compile/optimization operations
SD_CAPTION_DEBUG: enable captioning subsystem debug logs
SD_SECRETS_DEBUG: trace secrets handling operations
SD_UI_DEBUG: trace UI load/save debug operations

Override variables

These environment variables override paths and configuration files used by SD.Next.

SD_MODEL: load a specific checkpoint on startup
SD_DATADIR: override the base user data directory
SD_MODELSDIR: override the default models directory
SD_EMBEDDINGSDIR: override the embeddings directory
SD_VAEDIR: override the VAE directory
SD_LORADIR: override the LoRA directory
SD_EXTENSIONSDIR: override the extensions directory
SD_CONFIG: use a custom configuration file
SD_SECRETS: use a custom secrets file
SD_UICONFIG: use a custom UI configuration file
SD_PATH_PARAMS: override the params.txt file path
SD_HFCACHEDIR: override the HuggingFace cache directory

Runtime / workflow

The following environment variables can change startup behavior, server settings, and workflow execution.

SD_FREEZE: disable editing settings
SD_MEDVRAM: enable medium VRAM mode
SD_LOWVRAM: enable low VRAM mode
SD_DISABLE: disable specific UI tabs
SD_NO_CACHE: disable file caching
SD_KANVAS_DISABLE: disable Kanvas extension support
SD_VAE_DEFAULT: force default VAE output mode
SD_PORT: override the web server port
SD_SERVERNAME: override the server hostname
SD_SUBPATH: set the URL subpath for reverse proxies
SD_THEME: override the UI theme
SD_LOCALE: override the UI locale
SD_AUTH: set basic auth credentials
SD_AUTHFILE: set an auth credentials file
SD_MONITOR: enable memory monitoring mode
SD_STATUS: enable server status check mode

Note: SD_INSTALL_QUIET is primarily used in test environments to suppress installer output and is not a normal runtime debug flag.

Core processing

SD_DISABLE_PBAR: disable progress bar for all operations
SD_PROCESS_DEBUG: print detailed processing information
SD_DIFFUSERS_DEBUG: increase verbosity of diffusers processing
SD_LDM_DEBUG: increase verbosity of LDM processing
SD_CONTROL_DEBUG: report all debug information related to control module
SD_PROMPT_DEBUG: print all prompt parsing and encoding information
SD_SAMPLER_DEBUG: report all possible sampler settings for selected sampler
SD_STYLES_DEBUG: report styles processing information
SD_STEPS_DEBUG: report calculations done to scheduler steps
SD_VAE_DEBUG: report details on all VAE operations
SD_VIDEO_DEBUG: report all video processing operations as they happen

Networks

SD_EN_DEBUG: report all extra networks operations as they happen
SD_LORA_DEBUG: increase verbosity of LoRA loading and execution
SD_LORA_DUMP: dump LoRA key information during loading
SD_TI_DEBUG: enable textual inversion debug traces

Other

SD_SAVE_DEBUG: report all params and metadata save operations as they happen
SD_PASTE_DEBUG: report all params paste and parse operations as they happen
SD_HDR_DEBUG: print HDR processing information
SD_MASK_DEBUG: report detailed information on image masking operations as they happen
SD_DOWNLOAD_DEBUG: report detailed information on model download operations as they happen
SD_CALLBACK_DEBUG: report each step as it executes with full details
SD_BROWSER_DEBUG: report all gallery operations as they happen
SD_NAMEGEN_DEBUG: report all filename generation operations as they happen
SD_PULID_DEBUG: debug logging for pulid operations
SD_PREVIEW_DEBUG: debug logging for live preview operations
SD_LLM_DEBUG: debug logging for LLM operations
SD_XYZ_DEBUG: enable XYZ script debug traces
SD_GRADING_DEBUG: enable grading processing debug logs

Example Windows:

set SD_PROCESS_DEBUG=true
webui.bat --debug

Example Linux:

export SD_PROCESS_DEBUG=true
webui.sh --debug

Additional information enabled through environment variables appears in logs at TRACE level.

Profiling

To run SD.Next in profiling mode, start it with --profile flag
This adds CPU/GPU and memory overhead, so it is not recommended for daily use.
SD.Next will collect profiling information from both Python, Torch and CUDA and print it upon completion of specific operations

Use environment variables to control profiler behavior:

SD_PROFILE_FLOPS: enable FLOPs profiling
SD_PROFILE_SHAPES: record tensor shapes during profiling
SD_PROFILE_STACK: enable stack tracing in the profiler
SD_PROFILE_FOLDER: write profiler trace output to the given folder

Example:

webui.bat --debug --profile
webui.sh --debug --profile

Monitoring

SD.Next memory usage can be monitored using --monitor PERIOD flag in which case,
it will print detailed memory statistics for both CPU and GPU every n seconds.

Example:

webui.sh --debug --monitor

Crashes

If SD.Next crashes during its code, it will produce traceback in the console output
If traceback is not present and the process simply exits, that typically means the crash happened at the system level and app-level traceback could not be captured.

In that case, please check system logs for more information:

Linux: kernel logs dmesg -ku
Windows: Event Viewer -> Windows Logs -> Application/System

Tracebacks

If runtime error occurs during SD.Next processing, traceback will be printed in the console output
Level of information in the traceback can be further increased by setting env variables:

SD_TRACELINES: number of extra lines to show around the error line
SD_TRACEFRAMES: number of frames to show in the traceback
SD_TRACEWIDTH: width of the traceback output
SD_TRACEWRAP: enable word wrapping in the traceback
SD_TRACEINDENT: enable indent guides in the traceback
SD_TRACELOCALS: show local variables in the traceback
SD_TRACEDUNDER: show dunder variables in the traceback locals
SD_TRACESUNDER: show single underscore variables in the traceback locals