jax.diagnostics

Debug JAX errors from the traceback.

Get a repair link for tracer errors, NaNs, and accelerator failures. Add one wrapper to your Python training entry point or install the agent skill to diagnose saved errors.

Add to train.py
Traceback preview
jax.errors.TracerBoolConversionError:
Attempted boolean conversion of traced array.
JAX-TRACE-003 Traced Python boolean conversion Open repair guide

Use it in your training script

Install with Python 3.11 or newer. Wrap the host-side entry point, outside JIT. When a failure matches a guide, the wrapper adds a note and re-raises the original exception.

Install from PyPI

python -m pip install jax-diagnostics

train.py

from jax_diagnostics import annotate_errors

if __name__ == "__main__":
    with annotate_errors():
        main()

Install the agent skill

Run this in your project with Node.js 22.20 or newer. Choose your coding agent when prompted.

npx skills add mlnomadpy/jax-diagnostics

JAX debugging guides

The catalog covers all 12 public JAX exception types at the pinned revision. It also routes common backend and training symptoms.

See the full diagnostic catalog