Check your environment

nsx doctor is the one command that looks at your machine rather than at an app. It does not need a board, an app directory or a network connection. Run it after installing, and run it again first whenever a build or a flash misbehaves, because it separates a broken environment from a broken app.

nsx doctor

A passing run is on the Install page. This page is about what the checks mean and what to do when one fails.

What it checks

Check	Required	What a pass means
Python	yes	The interpreter running NSX, and its path.
uv	yes	`uv` is on `PATH`.
cmake	yes	CMake is on `PATH`.
ninja	yes	Ninja is on `PATH`.
git	yes	Git is on `PATH`. The line under it prints the protocol allow-list NSX uses when it clones module sources.
Board registry	yes	The board descriptors packaged with your NSX version load and agree with each other.
arm-none-eabi-gcc	yes	The default cross compiler is on `PATH`.
armclang, armlink, fromelf	no	Three checks, reported only when the Arm Compiler toolchain is found. Otherwise a single note says it was not detected.
ATfE	no	Reported only when `ATFE_ROOT` points at an install. Otherwise a note says it was not detected.
SEGGER J-Link	yes	`JLinkExe` was found.
SEGGER JLinkSWOViewerCL	yes	The SWO viewer binary was found on `PATH`.
SEGGER J-Link runtime	yes	`JLinkExe` was launched and started cleanly, which catches a broken install rather than a missing one.

Most checks print the path they resolved on the line beneath, so a pass also tells you which tool was picked up when you have more than one installed. Board registry and SEGGER J-Link runtime print a status line instead.

Reading a failure

Failures are per check. The command exits with status 1 and each failing check carries a hint naming what to install.


        $
        nsx doctor
      
        
        [OK] Python
      
        
        [OK] uv
      
        
        [OK] cmake
      
        
        [OK] ninja
      
        
        [OK] git
      
        
        [OK] Board registry
      
        
        [FAIL] arm-none-eabi-gcc
      
        
          Hint: Install the Arm GNU toolchain and ensure it is in PATH.
      
        
          (armclang toolchain not detected — optional)
      
        
          (ATfE toolchain not detected — set ATFE_ROOT to enable; optional)
      
        
        [OK] SEGGER J-Link
      
        
        [FAIL] SEGGER JLinkSWOViewerCL
      
        
          Hint: Install the SEGGER J-Link package and ensure JLinkSWOViewerCL is in PATH.
      
        
        [OK] SEGGER J-Link runtime
      
        
        Next: install or fix the failing tool above, then re-run `nsx doctor`.
      
        
        error: One or more required tools are missing or misconfigured.

Captured on macOS 26 on a host where the Arm GNU toolchain was not on PATH and the SEGGER SWO viewer was not installed. Resolved paths are omitted because they are specific to the machine that ran it.

Two things worth knowing from that output:

The optional toolchain notes are not failures. A host with only GCC is a supported host.
The SEGGER checks fail on any machine without the J-Link pack. If you do not have a board yet, that is expected and you can still work through Create your first app and Configure and build. Install the pack before you reach Flash, reset and view.

Machine-readable output

--json is doctor’s only option. It emits an object with ok, a checks array and notes, where each check carries label, ok, required, detail and hint. Use it from CI or from an agent rather than parsing the human output.

nsx doctor --json

Full option details are on the nsx doctor reference page.

Environment healthy, or at least healthy enough to build? Create your first app.