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:The stack’s own API keeps serving on its port; the debug build runs beside it.
terminal
2
Start a debug session
Build the API with debug flags and run it under Delve on a free port:The service runs with the dev env’s configuration, the same values
terminal
Output
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 A bare file name matches by suffix when it is unique. A bare method name,
CreateProduct has its result, in internal/handlers/catalog/handlers_crud.go:terminal
Output
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 The second If no request arrives within the timeout,
idp-steps.yaml and create a product against the debug port:terminal
curl hangs, because the handler is stopped. Back in the first terminal, wait for the stop:terminal
Output
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
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.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.tomlruns on127.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
starting dlv exec: exec: "dlv": executable file not found in $PATH
starting dlv exec: exec: "dlv": executable file not found in $PATH
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.database not reachable yet — retrying
database not reachable yet — retrying
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.Could not attach to pid …: this could be caused by a kernel security setting
Could not attach to pid …: this could be caused by a kernel security setting
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.