# Debug Mode

> Enable debug mode to get detailed logging of the AG-UI event pipeline on both the server and client.

# Debug Mode

When your agent isn't behaving as expected (events are missing, state isn't
updating, or tool calls aren't executing), you need visibility into the event
pipeline. Runtime debug mode provides structured server-side logging; the
frontend can inspect the resulting stream with browser network tools or the
AG-UI Event Inspector.

Enable it to see:
- What events your agent is emitting and whether they reach the client
- Where in the pipeline events are being dropped or failing validation
- The full lifecycle of a request from start to finish

<Callout type="info">
  For visual error display during local development (error banners, dev console), see [Error Debugging](/troubleshooting/error-debugging). Debug mode focuses on event pipeline logging rather than UI-level error display.
</Callout>

## Enabling Debug Mode [#enabling-debug-mode]

### Server-Side (Runtime) [#server-side-runtime]

Pass `debug: true` to the `CopilotRuntime` constructor:

```ts title="app/api/copilotkit/route.ts"
const runtime = new CopilotRuntime({
  agents: {
    // your agents
  },
  debug: true, // [!code highlight]
});
```

This produces structured Pino logs (formatted by `pino-pretty`) with a `copilotkit-debug` component label:

```
[14:32:01.123] DEBUG (copilotkit-debug): Agent run started
    agentName: "default"
    threadId: "abc-123"
[14:32:01.130] DEBUG (copilotkit-debug): SSE stream opened
[14:32:01.145] DEBUG (copilotkit-debug): Event emitted
    type: "TEXT_MESSAGE_START"
    messageId: "msg-1"
    role: "assistant"
[14:32:01.200] DEBUG (copilotkit-debug): Event emitted
    type: "TEXT_MESSAGE_CONTENT"
    deltaLength: 42
[14:32:01.250] DEBUG (copilotkit-debug): Event emitted
    type: "TEXT_MESSAGE_END"
[14:32:01.260] DEBUG (copilotkit-debug): Event emitted
    type: "RUN_FINISHED"
[14:32:01.261] DEBUG (copilotkit-debug): SSE stream completed
    eventCount: 4
    loggedEventCount: 4
```

<Callout type="warn">
  Do not turn on debug mode in production. Debug mode writes a large volume of logs, especially in verbose mode.
</Callout>

## Granular Configuration [#granular-configuration]

On `CopilotRuntime`, pass an object instead of `true` for fine-grained control
over what gets logged:

```ts
debug: {
  events: true,     // Log every event emitted/received
  lifecycle: true,  // Log request/run lifecycle (start, finish, error)
  verbose: false,   // Log full payloads instead of summaries
}
```

### Defaults [#defaults]

| Input | `events` | `lifecycle` | `verbose` |
|-------|----------|-------------|-----------|
| `debug: true` | `true` | `true` | `false` |
| `debug: {}` | `true` | `true` | `false` |
| `debug: { events: false }` | `false` | `true` | `false` |

When `debug` is a boolean (`true`), events and lifecycle logging are enabled but verbose mode is **off** by default (to avoid leaking PII in logs). To get full event payloads, explicitly opt in with `debug: { verbose: true }`.

### Examples [#examples]

Log only lifecycle events (no per-event logs):

```ts
debug: { events: false, lifecycle: true }
```

Log events with full payloads but skip lifecycle:

```ts
debug: { events: true, lifecycle: false, verbose: true }
```

## Troubleshooting with Debug Mode [#troubleshooting-with-debug-mode]

### Events Not Reaching the Client [#events-not-reaching-the-client]

Turn on debug mode on the server, then:

1. Find `Event emitted` in the server logs. Make sure that the expected events are there.
2. Make sure that `SSE stream completed` shows the expected `eventCount`.
3. Open the Network tab in the browser. Make sure that the SSE events arrive.

### Tool Calls Not Executing [#tool-calls-not-executing]

Turn on debug mode on the server, then:

1. Find `TOOL_CALL_START` in the server logs.
2. Make sure that `TOOL_CALL_ARGS` and `TOOL_CALL_END` follow it.
3. Make sure that the same events appear in the SSE stream in the Network tab.

### State Not Updating [#state-not-updating]

Look for `STATE_SNAPSHOT` or `STATE_DELTA` events in server logs. If they appear in the server logs but not in the browser's SSE stream, something between the server and the browser drops them. Open the Network tab and make sure that a proxy does not buffer or cut off the response.

## What Gets Logged [#what-gets-logged]

### Server-Side Logs [#server-side-logs]

| Category | Log Message | Description |
|----------|-------------|-------------|
| Lifecycle | `Agent run started` | An agent run was initiated, includes agent name and thread ID |
| Lifecycle | `SSE stream opened` | The SSE response stream was created |
| Lifecycle | `SSE stream completed` | The stream finished, includes total event count |
| Lifecycle | `SSE stream errored` | The stream encountered an error |
| Events | `Event emitted` | Each AG-UI event as it's written to the stream |

In **summary mode** (verbose off), event logs include key identifiers like `messageId`, `toolCallId`, `toolCallName`, `role`, and content lengths instead of full payloads.
