For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /max/get-started.md).
Python class
DebugConfig
DebugConfig
class max.engine.DebugConfig
Bases: object
Unified debug configuration for MAX inference.
DebugConfig is a process-wide singleton accessed through
InferenceSession.debug. It controls model debugging features
such as NaN checks, synchronous GPU execution, stack traces, and IR
dumping.
There are two ways to configure debugging options:
- Set the
MODULAR_DEBUGenvironment variable to a list of kebab-case property names separated by commas. Boolean properties can be enabled with just the name; others usename=valueform. For example:MODULAR_DEBUG=nan-check,assert-level=all. - Set properties directly with the Python API, for example
InferenceSession.debug.<property> = <value>. Options are class-level onInferenceSessionbecause they affect globally shared infrastructure.
For the environment variable and config file, the name sensible
enables a curated default set defined in sensible_mode.
assert_level
property assert_level
A string that sets the Mojo assertion level for compiled kernels. One of '', 'none', 'warn', 'safe', 'all'. Higher levels enable more runtime checks (e.g. LayoutTensor bounds) at a performance cost. Takes effect at model build time.
device_sync_mode
property device_sync_mode
A boolean that, when True, triggers MAX to force synchronous GPU execution so every device operation waits for completion. This surfaces async errors at their call site but serializes the pipeline. Takes effect at run time.
ir_output_dir
property ir_output_dir
A string path to the directory into which MAX dumps intermediate compiler IR for inspection. Empty string disables dumping. Takes effect at model build time.
nan_check
property nan_check
A boolean that, when True, triggers MAX to insert runtime checks after each compiled op that abort if any output contains NaN. Takes effect at model build time.
op_log_level
property op_log_level
A string that sets the log level for per-op tracing. One of '', 'notset', 'trace', 'debug', 'info', 'warning', 'error', 'critical'. Takes effect at model build time.
print_style
property print_style
A PrintStyle value that sets the format for tensor debug printing. Takes effect at run time.
profiling_active_steps
property profiling_active_steps
Number of model.execute() iterations to record once warmup completes. Defaults to 10. Mirrored by the MODULAR_MAX_DEBUG_PROFILING_ACTIVE_STEPS environment variable. Currently a no-op; takes effect once session.profiling.start() drives trace collection.
profiling_dynolog_enabled
property profiling_dynolog_enabled
Opt a daemon-mode process out of Dynolog registration. Only has an effect when the process is launched with KINETO_USE_DAEMON=1 – that env var is what turns on-demand capture on (libkineto keys its IPC client on it), registering the PID at device creation so dyno gputrace works with no other setup. This knob then defaults to True and is the off switch. Mirrored by MODULAR_MAX_DEBUG_PROFILING_DYNOLOG_ENABLED.
profiling_enabled
property profiling_enabled
A boolean master switch for the libkineto-backed HTA/Dynolog profiler. Defaults to False. Mirrored by the MODULAR_MAX_DEBUG_PROFILING_ENABLED environment variable. Currently a no-op; takes effect once session.profiling.start() drives trace collection.
profiling_output_path
property profiling_output_path
Where to write the Chrome-trace JSON. Accepts a file path; supports {pid} and {rank} template substitution and directory mode (existing-directory paths auto-generate trace_rank<rank>_<pid>_<unix-ts>_<seq>.json inside). An empty value lets Range.cpp fall back to its built-in default. Mirrored by MODULAR_MAX_DEBUG_PROFILING_OUTPUT_PATH.
profiling_periodic_flush_seconds
property profiling_periodic_flush_seconds
Cadence (in seconds) at which in-flight trace chunks are flushed to disk. Defaults to 60. Mirrored by the MODULAR_MAX_DEBUG_PROFILING_PERIODIC_FLUSH_SECONDS environment variable. Currently a no-op; today the trace is written synchronously when profiling stops.
profiling_warmup_steps
property profiling_warmup_steps
Number of model.execute() iterations to skip before active trace recording begins. Defaults to 0. Mirrored by the MODULAR_MAX_DEBUG_PROFILING_WARMUP_STEPS environment variable. Currently a no-op; takes effect once session.profiling.start() drives trace collection.
reset()
reset(self) → None
Reset all debug options to their defaults.
sensible_mode
property sensible_mode
A boolean that, when True, triggers MAX to enable a curated default debugging set, including nan_check, assert_level='all', device_sync_mode, stack_trace_on_error, stack_trace_on_crash, and source_tracebacks. You can override the defaults using individual properties.
source_tracebacks
property source_tracebacks
A boolean that, when True, triggers MAX to capture Python source locations during graph construction so runtime errors can be traced back to user code. Takes effect at graph build time and is typically set using Graph.debug.source_tracebacks.
stack_trace_on_crash
property stack_trace_on_crash
A boolean that, when True, triggers MAX to print a C++ stack trace on fatal signals such as SIGSEGV or SIGABRT. Takes effect at run time.
stack_trace_on_error
property stack_trace_on_error
A boolean that, when True, triggers MAX to print a C++ stack trace whenever a runtime error is raised. Takes effect at run time.
uninitialized_read_check
property uninitialized_read_check
A boolean that, when True, triggers MAX to instrument buffer reads to detect reads of uninitialized memory. Takes effect at model build time.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!