Learn how to debug errors in CopilotKit with dev console and set up error observability for monitoring services.

How to Debug Errors

CopilotKit provides visual error display for local development and debugging. This feature is completely free and requires no API keys.

Quick Setup#

import { CopilotKit } from "@copilotkit/react-core/v2";

export default function App() {
  return (
    <CopilotKit
      runtimeUrl="<your-runtime-url>"
      showDevConsole={true} 
    >
      {/* Your app */}
    </CopilotKit>
  );
}

Avoid showing the dev console in production as it exposes internal error details to end users.

When to Use Development Debugging#

Local development - See errors immediately in your UI
Quick debugging - No setup required, works out of the box
Testing - Verify error handling during development

Programmatic Error Handling (v2)#

The v2 API provides an onError callback on both CopilotKit and CopilotChat for programmatic error handling. No publicApiKey is required.

Provider-Level Error Handling#

Catches all errors across the entire application:

import { CopilotKit } from "@copilotkit/react-core/v2";

<CopilotKit
  runtimeUrl="/api/copilotkit"
  onError={(event) => {
    // event.code — error type (e.g. "runtime_info_fetch_failed", "agent_run_failed")
    // event.error — the Error object
    // event.context — additional context (agentId, toolName, etc.)
    console.error(`[CopilotKit ${event.code}]`, event.error.message);
    errorTracker.capture(event);
  }}
>
  <App />
</CopilotKit>

Chat-Level Error Handling#

Scoped to a specific chat's agent — fires in addition to the provider-level handler:

import { CopilotChat } from "@copilotkit/react-core/v2";

<CopilotChat
  agentId="my-agent"
  onError={(event) => {
    showToast(`Agent error: ${event.error.message}`);
  }}
/>

Error Codes#

Code	Description
`runtime_info_fetch_failed`	Could not reach the runtime `/info` endpoint
`agent_connect_failed`	Agent connection (thread setup) failed
`agent_run_failed`	Agent run rejected (e.g. network error)
`agent_run_failed_event`	Agent's `onRunFailed` subscriber fired
`agent_run_error_event`	Agent sent a `RUN_ERROR` event
`tool_argument_parse_failed`	Tool call arguments were not valid JSON
`tool_handler_failed`	A frontend tool handler threw an error

Need to see the raw AG-UI events flowing between runtime and client? Use the AG-UI Event Inspector in VS Code for a live, filterable event stream.

Need to see the full event pipeline — what events your agent emits, whether they reach the client, and where they're dropped? See Debug Mode for detailed AG-UI event logging.

Troubleshooting#

Development Debugging Issues#

Dev console not showing:
- Confirm showDevConsole={true}
- Check for JavaScript errors in the browser console
- Ensure no CSS is hiding the error banner

Error Debugging & Observability