JAX Diagnostics
Put a repair guide in the traceback. JAX Diagnostics is a standalone Python library, CLI, and agent skill for JAX errors. It follows the diagnostic pattern in Solid 2.0. A matched failure gets a stable diagnostic ID and a link to the relevant guide.
Landing page · Documentation · Blog · Agent skill · Diagnostic guides
Install the agent skill
Run this from your project with Node.js 22.20 or newer and select your coding agent when prompted.
npx skills add mlnomadpy/jax-diagnostics
For a non-interactive Codex install, add --agent codex --yes. Add --global to install across projects. Then invoke $jax-diagnostics in Codex with the error and the failing operation or backend. The skill installer installs the guide and its files. The Python wrapper below is installed separately. Supported agents and installer options
Use it in training
Use Python 3.11 or newer and install from PyPI.
python -m pip install jax-diagnostics
Wrap the host-side entry point in train.py and run it as usual.
from jax_diagnostics import annotate_errors
if __name__ == "__main__":
with annotate_errors():
main()
For example, a TracerBoolConversionError gets this note below the original exception.
[JAX-TRACE-003] Traced Python boolean conversion
Agent repair guide: https://github.com/mlnomadpy/jax-diagnostics/blob/main/references/tracing.md#jax-trace-003
The wrapper preserves the exception type, traceback, and exit behavior. It runs diagnostics only when an exception leaves the block. Pass guide_base to link to a pinned revision or a mirror. The package has no runtime dependencies.
Diagnose a saved traceback
jax-diagnose TracerBoolConversionError
jax-diagnose --json < traceback.txt
From a checkout, python3 scripts/diagnose.py also works with Python 3.10 or newer. The CLI exits with status 1 when it finds no match.
Diagnostic guides
All 12 named exceptions in the pinned public jax.errors module have dedicated routes. Symptom matches suggest where to start inspecting a failure. Upstream error inventory
| Guide | What it covers |
|---|---|
| Tracing | Concretization, tracer escapes, Python and NumPy conversions, boolean indexing |
| Shapes and types | Symbolic dimensions, broadcasting, dtypes, indexing |
| Transforms and state | Jaxpr, PRNG key reuse, gradients, mapped axes, Flax state |
| Numerics and parity | NaNs, infinities, and cross-framework mismatches |
| Runtime and restore | Compilation, memory, sharding, collectives, Pallas, and Orbax |
Development
See the development and release guide for building the docs, testing the skill, and preparing PyPI artifacts.
License
MIT.
Metadata
Release files for jax-diagnostics 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jax_diagnostics-0.1.0.tar.gz | 14.9 kB | With provenance | Details for jax_diagnostics-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jax_diagnostics-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for jax_diagnostics-0.1.0-py3-none-any.whl |
Total release size: 22.9 kB
Release files / jax_diagnostics-0.1.0.tar.gz
| Download URL | jax_diagnostics-0.1.0.tar.gz |
|---|---|
| Size | 14.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fbbc1cd3e6ccebc0fb43c2f47fcec7e01c45e138ff5394599fdd8e2f1b5fc6ad
|
|
BLAKE2b-256 checksum How to use checksums |
961f41bf242139093b2dd52bb1d4a8b5b41d1fb9a59a54c51aff7c652bc8646f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / jax_diagnostics-0.1.0-py3-none-any.whl
| Download URL | jax_diagnostics-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36c55476e44e76f0df0bc9efcd796b00549d1921edc3e560be5f170af7cc7f78
|
|
BLAKE2b-256 checksum How to use checksums |
540305cdbeabe262f3717148684c0f946f04897915b75c85fbb3f7cc3c4822c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for jax-diagnostics 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for jax_diagnostics-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.