Skip to main content

Python class

DebugConfig

DebugConfig​

class max.engine.DebugConfig

source

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_DEBUG environment variable to a list of kebab-case property names separated by commas. Boolean properties can be enabled with just the name; others use name=value form. 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 on InferenceSession because 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

source

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

source

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

source

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

source

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

source

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

source

A PrintStyle value that sets the format for tensor debug printing. Takes effect at run time.

reset()​

reset(self) → None

source

Reset all debug options to their defaults.

sensible_mode​

property sensible_mode

source

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

source

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

source

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

source

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

source

A boolean that, when True, triggers MAX to instrument buffer reads to detect reads of uninitialized memory. Takes effect at model build time.

Models

Cookbook

Puzzles

Blog

Community

Contact