# Error Debugging & Observability

> Surface errors visually in development, and wire programmatic error handlers for Sentry / Datadog / your analytics pipeline in production.

# How to debug errors [#how-to-debug-errors]

When a run fails, you need to see the error while you develop and send it to your error tracker in production. Turn on the dev console for development. The dev console shows error banners and toasts in your app. Then add an `onError` handler for production.

## Quick setup [#quick-setup]

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

export default function App() {
  return (
    <CopilotKit
      runtimeUrl="/api/copilotkit"
      showDevConsole={true} // [!code highlight]
    >
      {/* your app */}
    </CopilotKit>
  );
}
```

`showDevConsole` is deprecated. It still turns on the error banners and toasts of the dev console. For the Inspector, use `enableInspector`.

To check the setup, stop your runtime and reload the page. An error banner appears. Click **Show Details** to see the code `runtime_info_fetch_failed`.

<Callout type="warn">
Avoid showing the dev console in production. It exposes internal error details to end users.
</Callout>

## When to use development debugging [#when-to-use-development-debugging]

- **Local development**: errors appear immediately in your UI
- **Quick debugging**: no setup required, works by default
- **Testing**: verify error handling during development

## Programmatic error handling [#programmatic-error-handling]

Pass `onError` to the provider to catch every error, or to `CopilotChat` to catch the errors of one chat.

### Provider-level error handling [#provider-level-error-handling]

Catches every error across the entire application:

```tsx
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 [#chat-level-error-handling]

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

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

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

### Errors replayed from thread history [#errors-replayed-from-thread-history]

Connecting to an existing thread replays its history, including a `RUN_ERROR` from an earlier run. `onError` receives that error with the code `agent_run_error_event`, like a live failure. `event.context.phase` tells them apart: `"live"` for a run happening now, `"replay"` for thread history, and `"unknown"` when the connection can't tell.

If your handler shows a banner, skip only `"replay"`. Keep `"unknown"` visible, so a live failure is never hidden:

```tsx
import {
  CopilotKitProvider,
  CopilotKitCoreErrorCode,
} from "@copilotkit/react-core/v2";

<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  onError={(event) => {
    errorTracker.capture(event); // Still record every error.
    if (
      event.code === CopilotKitCoreErrorCode.AGENT_RUN_ERROR_EVENT &&
      event.context.phase === "replay"
    ) {
      return; // An earlier run's failure, replayed on connect.
    }
    showErrorBanner(event.error.message);
  }}
>
  <App />
</CopilotKitProvider>;
```

### Error codes [#error-codes]

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

<Callout type="info">
To see every event your agent emits and where events drop, open the [Inspector](../inspector). When a run fails, the launcher turns red. Click the launcher to open the pane for the failure. The pane shows the agent, the tool if one failed, and the error.
</Callout>

## Troubleshooting [#troubleshooting]

### Dev console not showing [#dev-console-not-showing]

- Confirm `showDevConsole={true}`
- Check for JavaScript errors in the browser console
- Make sure that no CSS hides the error banners of the dev console

### Production error pipeline checklist [#production-error-pipeline-checklist]

- Provider-level `onError` is wired and forwards to your error tracker
- `showDevConsole` is **false** in production builds
- Agent IDs in errors match the agents registered on your runtime
- Critical error codes (`agent_run_failed`, `tool_handler_failed`) are alerted on, not just logged
