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:
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: 4Do 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
| 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
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:
- Find
Event emittedin the server logs. Make sure that the expected events are there. - Make sure that
SSE stream completedshows the expectedeventCount. - 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:
- Find
TOOL_CALL_STARTin the server logs. - Make sure that
TOOL_CALL_ARGSandTOOL_CALL_ENDfollow it. - 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
| 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.
How is this guide?