Debugger

The Noir debugger is experimental. Its interface may change between releases.

Noir provides two debugging interfaces:

REPL debugger — a terminal-based interactive session launched with nargo debug.
VS Code debugger — a graphical debugger via the vscode-noir extension, using the Debug Adapter Protocol (DAP).

Both interfaces require Noir and Nargo ≥ 0.28.0. The VS Code debugger additionally requires vscode-noir ≥ 0.0.11.

REPL debugger

Starting the debugger

From your project directory, run:

nargo debug

The debugger compiles your program, loads inputs from Prover.toml, and presents an interactive prompt:

[hello_world] Starting debugger
At ~/hello_world/src/main.nr:1:9
  1 -> fn main(x : Field, y : pub Field) {
  2        assert(x != y);
  3    }
>

To debug a specific test function instead of main, use --test-name:

nargo debug --test-name test_my_function

Command-line options

Option	Description
`[WITNESS_NAME]`	Write the execution witness to this file name when execution completes.
`-p, --prover-name <NAME>`	Input TOML file name. Defaults to `Prover`.
`--package <NAME>`	Package to debug.
`--test-name <NAME>`	Name or substring of a test function to debug instead of `main`.
`--acir-mode`	Compile to ACIR without debug instrumentation. Disables `vars`.
`--skip-instrumentation <BOOL>`	Disable variable tracing instrumentation.
`--oracle-resolver <URL>`	JSON-RPC URL for resolving oracle calls.

REPL commands

Type help at the prompt to view all available commands:

> help
Available commands:

  opcodes                          display ACIR opcodes
  into                             step into to the next opcode
  next                             step until a new source location is reached
  out                              step until a new source location is reached
                                   and the current stack frame is finished
  over                             step until a new source location is reached
                                   without diving into function calls
  step                             step to the next ACIR opcode
  continue                         continue execution until the end of the program
  restart                          restart the debugging session
  break LOCATION:OpcodeLocation    add a breakpoint at an opcode location
  break line:i64                   add a breakpoint at an opcode associated to the given source code line
  delete LOCATION:OpcodeLocation   delete breakpoint at an opcode location
  vars                             show variable values available at this point in execution
  witness                          show witness map
  witness index:u32                display a single witness from the witness map
  witness index:u32 value:String   update a witness with the given value
  memory                           show memory (valid when executing unconstrained code)
  memset index:usize value:String  update a memory cell with the given value
  stacktrace                       display the current stack trace

Other commands:

  help  Show this help message
  quit  Quit repl

Stepping commands

next (n) — step to the next source location

Advances execution to the next line in the Noir source code. If the current line calls a function, next steps into that function.

  fn main(x: u32) {
      assert(entry_point(x) == 2);
->     assert(deep_entry_point(x) == 4);
      multiple_values_entry_point(x);
  }

Using next at line 3 steps into deep_entry_point.

over — step over function calls

Advances to the next source location without descending into called functions. Use this when you want to skip over a function call and continue at the next statement.

  3 ->     assert(deep_entry_point(x) == 4);
  4        multiple_values_entry_point(x);

Using over at line 3 advances directly to line 4.

out — step out of the current function

Continues execution until the current function returns, then pauses at the call site.

step (s) — step to the next ACIR opcode

Advances one ACIR opcode at a time. When paused at a BRILLIG opcode (start of an unconstrained block), step skips the entire unconstrained block and moves to the next ACIR opcode. Use into to enter unconstrained blocks instead.

into (i) — step into the next opcode (including unconstrained)

Advances one opcode at a time, entering unconstrained (Brillig) blocks step by step.

->  BRILLIG inputs=[...]
0  |   Mov { destination: RegisterIndex(2), source: RegisterIndex(0) }
1  |   Const { destination: RegisterIndex(0), value: Value { inner: 0 } }

Using into at the BRILLIG opcode pauses at opcode 1.0.

continue (c) — run until breakpoint or end

Resumes execution, running until the next breakpoint is hit or the program finishes.

> continue
(Continuing execution...)
Finished execution

restart (res) — restart the session

Interrupts the current debugging session and starts a new one from the beginning.

Breakpoints

Set a breakpoint at a specific opcode index:

> break 1.2

Set a breakpoint at a source code line:

> break 15

The breakpoint is shown with a * marker in the opcode listing:

->  BRILLIG inputs=[...]
0  |   Mov ...
1  |   Const ...
2  | * Const ...

Delete a breakpoint:

> delete 1.2

Inspecting variables

Use vars to display the current values of local variables at the current execution point:

> vars
x:Field = 0x01
y:Field = 0x02

Variable inspection requires debug instrumentation, which is enabled by default. If you pass --acir-mode or --skip-instrumentation true, variable names will not be available and vars will return nothing.

Witness map

Display the entire witness map:

> witness
_0 = 1
_1 = 2

Display a single witness by index:

> witness 1
_1 = 2

Overwrite a witness value:

> witness 1 3
_1 = 3

Stack trace

> stacktrace

Displays the current call stack, showing which functions are active.

Unconstrained VM memory

These commands are only available while execution is inside an unconstrained (Brillig) block. Display memory:

> memory
0 = 1

Update a memory cell:

> memset 0 2

ACIR opcode listing

Display all ACIR opcodes for the compiled program:

> opcodes
0  BLACKBOX::RANGE [(_0, num_bits: 32)] [ ]
1 ->  BRILLIG inputs=[...] outputs=[...]
    1.0  |   Mov { destination: RegisterIndex(2), source: RegisterIndex(0) }
    ...
2    EXPR [ (1, _1) -2 ]

The -> marker shows the current execution position.

Example session

$ nargo debug

[hello_world] Starting debugger
At ~/hello_world/src/main.nr:1:9
  1 -> fn main(x : Field, y : pub Field) {
  2        assert(x != y);
  3    }
> witness
_0 = 1
_1 = 2
> next
  1    fn main(x : Field, y : pub Field) {
  2 ->     assert(x != y);
  3    }
> vars
x:Field = 0x01
y:Field = 0x02
> continue
(Continuing execution...)
Finished execution
> quit
[hello_world] Circuit witness successfully solved

VS Code debugger

The VS Code debugger provides a graphical debugging experience using the Debug Adapter Protocol.

Setup

Install the VS Code extension

Install vscode-noir from the Visual Studio Marketplace.

Open your Noir project

Open the folder containing your Nargo.toml directly as the VS Code workspace root. LSP features, including the debugger, require the workspace root to match the Noir project root.

Start debugging

Open any .nr file. You will see codelens buttons above main functions and #[test] functions:

Debug — launches the debugger for main
Debug test — launches the debugger for a specific test

You can also press F5 to start debugging the current file using Prover.toml as input.

VS Code debugger features

Variable inspection: The Debug pane shows two sections — Locals (current program variables) and Witness Map (values from Prover.toml). Stepping: Use the standard VS Code debugger toolbar buttons or keyboard shortcuts to step into, over, and out of functions. Breakpoints: Click to the left of a line number to set a breakpoint. Press F5 (Continue) to run until the breakpoint is hit. Hover values: Hover over a variable name in the source to see its current value. Call stack: The Call Stack pane shows the active function call hierarchy.

DAP integration

The debugger uses the Debug Adapter Protocol via the hidden nargo dap subcommand, which is launched automatically by the VS Code extension. You do not need to invoke this command directly.

Get Started

Language Guide

Standard Library

Tooling

REPL debugger

Starting the debugger

Command-line options

REPL commands

Stepping commands

Breakpoints

Inspecting variables

Witness map

Stack trace

Unconstrained VM memory

ACIR opcode listing

Example session

VS Code debugger

Setup

VS Code debugger features

DAP integration

Build docs developers (and LLMs) love

Get Started

Language Guide

Standard Library

Tooling

Documentation Index

​REPL debugger

​Starting the debugger

​Command-line options

​REPL commands

​Stepping commands

​Breakpoints

​Inspecting variables

​Witness map

​Stack trace

​Unconstrained VM memory

​ACIR opcode listing

​Example session

​VS Code debugger

​Setup

​VS Code debugger features

​DAP integration

Build docs developers (and LLMs) love

REPL debugger

Starting the debugger

Command-line options

REPL commands

Stepping commands

Breakpoints

Inspecting variables

Witness map

Stack trace

Unconstrained VM memory

ACIR opcode listing

Example session

VS Code debugger

Setup

VS Code debugger features

DAP integration