acton debug — source-level DAP debugging for Tolk

Acton does not have a standalone acton debug command. Instead, source-level debugging is activated by passing --debug to acton test or acton script. When the flag is present, Acton compiles the target code with debug metadata and source maps, then starts a local Debug Adapter Protocol (DAP) server that any compatible editor can attach to — including VS Code and IntelliJ/JetBrains IDEs.

For replaying a real historical transaction with source-level stepping, use acton retrace <HASH> --contract <NAME> --debug. That command is documented separately in the Command Reference.

Debug flags reference

acton test —debug

acton test [PATH] --debug [--debug-port PORT] [--backtrace MODE] [OPTIONS]

Flag	Type	Default	Description
`--debug`	flag	—	Enable the DAP debug server for test execution
`--debug-port`	number	`12345`	Port for the DAP server on `127.0.0.1`
`--backtrace`	enum	—	Backtrace mode without the debugger: `full`
`--filter`	string	—	Regex filter — narrow to one test for debug sessions
`--verbose`	flag	—	Increase executor log verbosity (level 1)

acton script —debug

acton script <PATH> --debug [--debug-port PORT] [--backtrace MODE] [OPTIONS]

Flag	Type	Default	Description
`--debug`	flag	—	Enable the DAP debug server for script execution
`--debug-port`	number	`12345`	Port for the DAP server on `127.0.0.1`
`--backtrace`	enum	—	Backtrace mode without the debugger: `full`
`--net`	string	—	Broadcast network (omit for local emulation)

Starting a debug session

Debug a test
Debug a script

# Narrow to one test with --filter, then attach
acton test tests/counter.test.tolk --filter "deploy" --debug --debug-port 4711

Acton prints DAP server listening on 127.0.0.1:4711 when ready. Attach from your editor next.

For broad test suites, always narrow with --filter. Debugging all tests at once produces confusing interleaved stops and is much slower.

acton script scripts/deploy.tolk --debug --debug-port 4711

Script debugging runs the local emulation path. When --net is also set, Acton steps through the script logic but does not provide source-level stepping inside the actual on-chain wallet broadcast after the script hands off to the network.

Connecting VS Code

Using the TON VS Code extension (recommended)

Install the TON VS Code extension. The extension adds a dedicated Tolk debugger type and can auto-launch acton test --debug or acton script --debug from the IDE run panel.

Manual launch.json setup

If you prefer a manual configuration, create .vscode/launch.json in your project:

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "tolk",
      "request": "launch",
      "name": "Debug Test",
      "debugServer": 4711
    },
    {
      "type": "tolk",
      "request": "launch",
      "name": "Debug Script",
      "debugServer": 4712
    }
  ]
}

Then start the matching Acton command in a terminal before launching the VS Code debug configuration:

# Terminal 1: start the debug server
acton test tests/counter.test.tolk --filter "deploy" --debug --debug-port 4711

# Then launch "Debug Test" from the VS Code Run and Debug panel

The Acton DAP server must be running and listening before you launch the VS Code configuration. The server prints a ready message when it is accepting connections.

Debugger capabilities

The Acton debugger supports:

Feature	Supported
Source breakpoints	✅
Conditional breakpoints	✅ (fail-loud — evaluation failures surface as stops)
Continue, step over, step into, step out	✅
Instruction-level stepping	✅
Exception break filters	✅ (`Uncaught Exceptions`, `All Exceptions`)
Stack traces	✅
Local variable inspection	✅ (tuples, maps, arrays, structs, cells, unions)
Hover, watch, and debug-console evaluation	✅ (side-effect-free subset)
`Registers` scope (c4 storage, c5 actions, c7 temp)	✅ (live sessions only)
Nested send/get-method child sessions	✅
Step-back	❌
Data breakpoints	❌
Function breakpoints	❌

The Registers scope

Live debug sessions (test and script) expose a Registers scope in the Variables panel:

c4 (storage) — current contract storage, rendered in structured contract-aware form
c5 (output actions) — output actions already prepared in the current execution
c7 (temporary data) — runtime temporary data

This scope is available only for live sessions. acton retrace --debug sessions (replay mode) do not have the live register view.

Expression evaluation limits

Evaluation in watches, hover, and conditional breakpoints supports:

Local variables from the selected frame
Field access (foo.bar) and numeric indexing (foo.items.0)
Boolean, string, integer, and null literals
!, unary -, &&, ||, ==, !=, <, <=, >, >=
Typed cell casts: someCell as Cell<Foo> or someSlice as Cell<Foo>

Not supported: function calls, mutations, arbitrary arithmetic, general type casts.

evaluate is an inspection feature, not a full Tolk REPL. Use it for watches and conditional breakpoints, not for validating complex logic end to end.

Backtraces without the live debugger

When you need source locations and call-path attribution without setting up the full DAP workflow, use --backtrace full:

acton test --backtrace full
acton script scripts/deploy.tolk --backtrace full

Backtraces are the middle layer between plain terminal output and the interactive debugger. They show the chain of nested contract calls that led to a failure, including nested message-driven callers. Acton automatically prepares the required debug metadata — no extra build step needed.

--backtrace full is noticeably slower and more memory-hungry than a plain run because Acton compiles with richer debug metadata. Do not use it as the default for large test suites — narrow to the relevant file or use --filter first.

Debugging decision guide

Question	Best tool
Print a value from a test or script	`println(...)`
Print a value from TVM contract code	`debug.print*`
Inspect a transaction tree quickly	`println(txs)` / matcher output
Get source locations without a live debugger	`--backtrace full`
Set breakpoints and step through Tolk code	`acton test --debug` or `acton script --debug`
Debug a real historical on-chain transaction	`acton retrace <HASH> --contract <NAME> --debug`

Examples

acton test tests/counter.test.tolk --filter "deploy" --debug --debug-port 4711

Practical limits

acton test --debug is a poor fit for running an entire test suite — narrow to one test with --filter.
Live stepping into remote or forked contracts may still run, but source-level fidelity depends on having matching local debug info.
acton script --debug does not provide source-level stepping inside the real on-chain wallet broadcast after the script hands control to the network.
The debugger does not support step-back, data breakpoints, function breakpoints, or restart-style flows.

Command Reference

acton debug — source-level DAP debugging for Tolk

Debug flags reference

acton test —debug

acton script —debug

Starting a debug session

Connecting VS Code

Using the TON VS Code extension (recommended)

Manual launch.json setup

Debugger capabilities

The Registers scope

Expression evaluation limits

Backtraces without the live debugger

Debugging decision guide

Examples

Practical limits

See Also

Build docs developers (and LLMs) love

Command Reference

Documentation Index

​Debug flags reference

​acton test —debug

​acton script —debug

​Starting a debug session

​Connecting VS Code

​Using the TON VS Code extension (recommended)

​Manual launch.json setup

​Debugger capabilities

​The Registers scope

​Expression evaluation limits

​Backtraces without the live debugger

​Debugging decision guide

​Examples

​Practical limits

​See Also

Build docs developers (and LLMs) love

Debug flags reference

acton test —debug

acton script —debug

Starting a debug session

Connecting VS Code

Using the TON VS Code extension (recommended)

Manual launch.json setup

Debugger capabilities

The Registers scope

Expression evaluation limits

Backtraces without the live debugger

Debugging decision guide

Examples

Practical limits

See Also