Skip to content

error-debugging.mdx

Latest commit

 

History

History
99 lines (75 loc) · 3.03 KB

error-debugging.mdx

File metadata and controls

99 lines (75 loc) · 3.03 KB
Raw

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";

export default function App() {
  return (
    <CopilotKit
      runtimeUrl="<your-runtime-url>"
      showDevConsole={true} // [!code highlight]
    >
      {/* 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 CopilotKitProvider and CopilotChat for programmatic error handling. No publicApiKey is required.

Provider-Level Error Handling

Catches all errors across the entire application:

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

<CopilotKitProvider
  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 />
</CopilotKitProvider>

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](/troubleshooting/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](/troubleshooting/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