mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Maxim
92 lines
2.6 KiB
Plaintext
92 lines
2.6 KiB
Plaintext
# 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
|
|
|
|
```tsx
|
|
import { CopilotKit } from "@copilotkit/react-core";
|
|
|
|
export default function App() {
|
|
return (
|
|
<CopilotKit
|
|
runtimeUrl="<your-runtime-url>"
|
|
showDevConsole={true} // [!code highlight]
|
|
>
|
|
{/* Your app */}
|
|
</CopilotKit>
|
|
);
|
|
}
|
|
```
|
|
|
|
<Callout type="warning">
|
|
Avoid showing the dev console in production as it exposes internal error details to end users.
|
|
</Callout>
|
|
|
|
## 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:
|
|
|
|
```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
|
|
|
|
Scoped to a specific chat's agent — 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}`);
|
|
}}
|
|
/>
|
|
```
|
|
|
|
### 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 |
|
|
|
|
## 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
|