> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug a running Go service from the terminal or an agent

> Stop a Forge Go service on a breakpoint inside a handler, send it a request, and read its arguments and locals with forge debug, one command per step.

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](https://github.com/go-delve/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](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md). 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:

```bash terminal theme={null}
reliant forge env up dev
```

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:

```bash terminal theme={null}
reliant forge dev debug start api --run --app-port 18080
```

```text Output theme={null}
Building ./cmd/shop with debug flags...
Debug session started for api
Configuration: workload "api" of env "dev"
Service PORT: 18080
Delve listening at 127.0.0.1:36075
Program output: .forge/logs/dev/debug_api.log
Target is RUNNING. Set breakpoints with 'forge debug break', then 'forge debug continue --timeout 60s' waits for the next hit.
```

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`:

```bash terminal theme={null}
reliant forge debug break handlers_crud.go:64
```

```text Output theme={null}
Breakpoint 4: …/internal/handlers/catalog/handlers_crud.go:64 (example.com/shop/internal/handlers/catalog.(*Service).CreateProduct)  hits=0
```

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:

```bash terminal theme={null}
curl -s -c cj -X POST localhost:18080/auth/login -H 'content-type: application/json' \
  -d '{"email":"admin@shop.localhost","password":"Password1!"}'
curl -s -b cj -X POST localhost:18080/services.catalog.v1.CatalogService/CreateProduct \
  -H 'content-type: application/json' -d '{"name":"Desk lamp","priceCents":"4500","inStock":true}'
```

The second `curl` hangs, because the handler is stopped. Back in the first terminal, wait for the stop:

```bash terminal theme={null}
reliant forge debug continue --timeout 60s
```

```text Output theme={null}
Stopped at …/internal/handlers/catalog/handlers_crud.go:64 (example.com/shop/internal/handlers/catalog.(*Service).CreateProduct)
Reason: breakpoint | Goroutine 135
```

If no request arrives within the timeout, `continue` exits non-zero and the service keeps running.

**5. Read the locals and arguments**

```bash terminal theme={null}
reliant forge debug locals
reliant forge debug eval 'req.Msg.Name'
reliant forge debug eval 'resp.Msg.Product.Id'
```

```text Output (trimmed) theme={null}
err                  error
                       void
resp                 *connectrpc.com/connect.Response[example.com/shop/gen/services/catalog/v1.CreateProductResponse] 70325102611336
    Msg                  *example.com/shop/gen/services/catalog/v1.CreateProductResponse 70325099991744
        Product              *example.com/shop/gen/services/catalog/v1.Product 70325093529840
req.Msg.Name         string                         Desk lamp
resp.Msg.Product.Id  string                         01M7WXW7GYPCDJ2Z50667X2D6J
```

`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`:

```bash terminal theme={null}
reliant forge debug eval 'req.Msg.PriceCents' --json
```

```json Output theme={null}
{"name":"req.Msg.PriceCents","type":"int64","value":"4500"}
```

`step`, `step-in` and `step-out` move through the code from here.

**6. Let the request finish and stop the session**

```bash terminal theme={null}
reliant forge debug continue --no-wait
reliant forge debug stop
```

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.

> [!WARNING]
>
> 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](https://docs.reliantlabs.io/guides/observability/debug-production-with-ai-agent.md). `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

> [accordion] 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`.

> [accordion] 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`.

> [accordion] 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

> [card] [Logs from browser and backend](https://docs.reliantlabs.io/guides/observability/browser-and-backend-logs-locally.md)
>
> Read every dev log, the browser console included, from one directory.

> [card] [Find your slowest endpoints](https://docs.reliantlabs.io/guides/observability/find-slowest-rpcs.md)
>
> Find the slow RPC first, then step through it.

> [card] [Debug production with an agent](https://docs.reliantlabs.io/guides/observability/debug-production-with-ai-agent.md)
>
> Investigate a hosted environment from its telemetry.

> [card] [forge debug reference](https://docs.reliantlabs.io/reference/cli.md#reliant-forge-debug)
>
> Every debug subcommand and flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.