Debug Mode

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

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

For visual error display during local development (error banners, dev console), see Error Debugging. Debug mode focuses on event pipeline logging rather than UI-level error display.

Enabling Debug Mode

Server-Side (Runtime)

Pass debug: true to the CopilotRuntime constructor:

app/api/copilotkit/route.ts
const runtime = new CopilotRuntime({
  agents: {
    // your agents
  },
  debug: true,
});

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

Do not turn on debug mode in production. Debug mode writes a large volume of logs, especially in verbose mode.

Granular Configuration

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

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

Inputeventslifecycleverbose
debug: truetruetruefalse
debug: {}truetruefalse
debug: { events: false }falsetruefalse

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

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

debug: { events: false, lifecycle: true }

Log events with full payloads but skip lifecycle:

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

Troubleshooting with Debug Mode

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

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

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

Server-Side Logs

CategoryLog MessageDescription
LifecycleAgent run startedAn agent run was initiated, includes agent name and thread ID
LifecycleSSE stream openedThe SSE response stream was created
LifecycleSSE stream completedThe stream finished, includes total event count
LifecycleSSE stream erroredThe stream encountered an error
EventsEvent emittedEach 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.

How is this guide?