Skip to main content

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

Skills.sh installs

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)

Source distribution for jax-diagnostics 0.1.0
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)

Table of built distributions (wheels) for jax-diagnostics 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page