Skip to main content
By the end of this guide you will have stopped your API inside a handler on a real request and read the request, the response and the local variables, from the command line. reliant forge debug drives the Delve debugger in separate, short commands: each one connects to the same session (saved in .forge/debug-session.json), prints, and exits. An agent can debug the same way it runs any other command, and every inspecting command takes --json.

Before you begin

  • A Forge Go project with an entity and its CRUD RPCs: Build a Go and React app. The examples use its CatalogService.
  • Delve on your PATH: go install github.com/go-delve/delve/cmd/dlv@latest.
  • Forge v1.6.1 or later in the project (reliant forge --version).
1

Start the stack

The service needs its database and sign-in provider, so bring the dev stack up first:
terminal
The stack’s own API keeps serving on its port; the debug build runs beside it.
2

Start a debug session

Build the API with debug flags and run it under Delve on a free port:
terminal
Output
The service runs with the dev env’s configuration, the same values env up gives it. --run lets it serve at once; without it the process waits at its entry point until you continue. --app-port is needed because the stack’s API already holds the configured port.
3

Set a breakpoint in a handler

Break on the line after CreateProduct has its result, in internal/handlers/catalog/handlers_crud.go:
terminal
Output
A bare file name matches by suffix when it is unique. A bare method name, reliant forge debug break CreateProduct, stops at the method’s first line instead. Add --cond 'req.Msg.PriceCents > 1000' to stop only on some requests.
4

Send a request and wait for the hit

In a second terminal, sign in as the development user from idp-steps.yaml and create a product against the debug port:
terminal
The second curl hangs, because the handler is stopped. Back in the first terminal, wait for the stop:
terminal
Output
If no request arrives within the timeout, continue exits non-zero and the service keeps running.
5

Read the locals and arguments

terminal
Output (trimmed)
args prints the function’s arguments (s, ctx, req), and stack prints the call stack down through the Connect interceptors. For a script or an agent, add --json:
terminal
Output
step, step-in and step-out move through the code from here.
6

Let the request finish and stop the session

terminal
The waiting curl now prints the created product. stop kills the debug build and its Delve server; the stack’s own API is untouched. Stop the stack with reliant forge env down dev when you are done.
Debugger output includes whatever the request carried. args prints req’s headers, session cookie included, so do not paste it into an issue or a chat.

What this does not do

  • It debugs a process on your machine. A Reliant-hosted environment is investigated from its logs, traces and issues instead: Debug production with an AI agent. debug connect <host:port> drives a Delve server someone else started, such as the one the scaffolded .air-debug.toml runs on 127.0.0.1:2345.
  • It does not pause anything else. Only the debug build stops at a breakpoint; the stack’s API on its usual port keeps answering.

Troubleshooting

Delve is not installed, or Go’s bin directory is not on your PATH. Run go install github.com/go-delve/delve/cmd/dlv@latest and check dlv version.
This line in .forge/logs/dev/debug_api.log means the dev stack is not running, so the service has no database. Run reliant forge env up dev.
debug start --attach <pid> attaches to a process that is already running. On Linux with kernel.yama.ptrace_scope set to 1, Delve may trace only processes it started. Use debug start <service> as in this guide, or allow the attach with sudo sysctl -w kernel.yama.ptrace_scope=0.

Next steps

Logs from browser and backend

Read every dev log, the browser console included, from one directory.

Find your slowest endpoints

Find the slow RPC first, then step through it.

Debug production with an agent

Investigate a hosted environment from its telemetry.

forge debug reference

Every debug subcommand and flag.