showcase/shell-docs/src/content/snippets/shared/troubleshooting/error-debugging.mdx
CopilotKit provides visual error display for local development and debugging. This feature is completely free and requires no API keys.
import { CopilotKit } from "@copilotkit/react-core";
export default function App() {
return (
<CopilotKit
runtimeUrl="<your-runtime-url>"
showDevConsole={true} // [!code highlight]
>
</CopilotKit>
);
}
The v2 API provides an onError callback on both CopilotKitProvider and CopilotChat for programmatic error handling. No publicApiKey is required.
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>
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}`);
}}
/>
| 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 |
showDevConsole={true}