Error Debugging & Observability

CopilotKit provides comprehensive error handling capabilities to help you debug issues and monitor your application's behavior. Whether you're developing locally or running in production, CopilotKit offers tools to capture, understand, and resolve errors effectively.

Quick Start

<Steps> <Step> ### Local Development with Dev Console

For local development, enable the dev console to see errors directly in your UI:

tsx

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

export default function App() {
  return (
    <CopilotKit
      runtimeUrl="<your-runtime-url>"
      showDevConsole={true} // [!code highlight]
    >
    </CopilotKit>
  );
}

<Callout type="tip"> The dev console shows error banner directly in your UI, making it easy to spot issues during development. **No API key required** for this feature. </Callout> </Step> <Step> ### Production Error Observability

For production applications, use error observability hooks to send errors to monitoring services (requires publicApiKey):

tsx

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

export default function App() {
  return (
    <CopilotKit
      runtimeUrl="<your-runtime-url>"
      publicApiKey="ck_pub_your_key" // [!code highlight]
      onError={(errorEvent) => {
        // [!code highlight]
        // Send to your monitoring service
        console.error("CopilotKit Error:", errorEvent);

        // Example: Send to analytics
        analytics.track("copilotkit_error", {
          type: errorEvent.type,
          source: errorEvent.context.source,
          timestamp: errorEvent.timestamp,
        });
      }} // [!code highlight]
      showDevConsole={false} // Hide dev console in production
    >
    </CopilotKit>
  );
}

<Callout type="info"> **Need a publicApiKey?** Go to [https://cloud.copilotkit.ai](https://cloud.copilotkit.ai) and get one for free! </Callout> </Step> </Steps>

Error Handling Options

Dev Console (`showDevConsole`)

The dev console provides immediate visual feedback during development:

tsx

<CopilotKit runtimeUrl="<your-runtime-url>" showDevConsole={true}>
</CopilotKit>

Features:

✅ No API key required - works with any setup
✅ Visual error banner - errors appear as banner in your UI
✅ Real-time feedback - see errors immediately as they occur
✅ Development-focused - detailed error information for debugging

Best for:

Local development
Testing and debugging
Understanding error flows

<Callout type="warn"> Set `showDevConsole={false}` in production to avoid showing error details to end users. </Callout>

Error Observability (`onError`)

The error observability hooks provide programmatic access to detailed error information for monitoring and analytics:

tsx

import { CopilotErrorEvent } from "@copilotkit/shared";

<CopilotKit
  publicApiKey="ck_pub_your_key"
  onError={(errorEvent: CopilotErrorEvent) => {
    // Send error data to monitoring services
    switch (errorEvent.type) {
      case "error":
        logToService("Critical error", errorEvent);
        break;
      case "request":
        logToService("Request started", errorEvent);
        break;
      case "response":
        logToService("Response received", errorEvent);
        break;
      case "agent_state":
        logToService("Agent state change", errorEvent);
        break;
    }
  }}
>
</CopilotKit>;

Features:

✅ Rich error context - detailed information about what went wrong
✅ Request/response tracking - monitor the full conversation flow
✅ Agent state monitoring - track agent interactions and state changes
✅ Production-ready - structured data perfect for monitoring services

Requirements:

Requires publicApiKey from Copilot Cloud
Part of CopilotKit's enterprise observability offering

<Callout type="info"> **Note:** Basic error handling works without Cloud. The `onError` hook is specifically for **error observability** - sending error data to monitoring services like Sentry, DataDog, etc. </Callout>

Error Event Structure

The onError handler receives detailed error events with rich context:

typescript

interface CopilotErrorEvent {
  type:
    | "error"
    | "request"
    | "response"
    | "agent_state"
    | "action"
    | "message"
    | "performance";
  timestamp: number;
  context: {
    source: "ui" | "runtime" | "agent";
    request?: {
      operation: string;
      method?: string;
      url?: string;
      startTime: number;
    };
    response?: {
      endTime: number;
      latency: number;
    };
    agent?: {
      name: string;
      nodeName?: string;
    };
    messages?: {
      input: any[];
      messageCount: number;
    };
    technical?: {
      environment: string;
      stackTrace?: string;
    };
  };
  error?: any; // Present for error events
}

Common Error Observability Patterns

Basic Error Logging

tsx

<CopilotKit
  publicApiKey="ck_pub_your_key"
  onError={(errorEvent) => {
    console.error("[CopilotKit Error]", {
      type: errorEvent.type,
      timestamp: new Date(errorEvent.timestamp).toISOString(),
      context: errorEvent.context,
      error: errorEvent.error,
    });
  }}
>
</CopilotKit>

Integration with Monitoring Services

tsx

// Example with Sentry
import * as Sentry from "@sentry/react";

<CopilotKit
  publicApiKey="ck_pub_your_key"
  onError={(errorEvent) => {
    if (errorEvent.type === "error") {
      Sentry.captureException(errorEvent.error, {
        tags: {
          source: errorEvent.context.source,
          operation: errorEvent.context.request?.operation,
        },
        extra: {
          context: errorEvent.context,
          timestamp: errorEvent.timestamp,
        },
      });
    }
  }}
>
</CopilotKit>;

Custom Error Analytics

tsx

<CopilotKit
  publicApiKey="ck_pub_your_key"
  onError={(errorEvent) => {
    // Track different error types
    analytics.track("copilotkit_event", {
      event_type: errorEvent.type,
      source: errorEvent.context.source,
      agent_name: errorEvent.context.agent?.name,
      latency: errorEvent.context.response?.latency,
      error_message: errorEvent.error?.message,
      timestamp: errorEvent.timestamp,
    });
  }}
>
</CopilotKit>

Development vs Production Setup

Development Environment

tsx

<CopilotKit
  runtimeUrl="http://localhost:3000/api/copilotkit"
  showDevConsole={true} // Show visual errors
  onError={(errorEvent) => {
    // Simple console logging for development
    console.log("CopilotKit Event:", errorEvent);
  }}
>
</CopilotKit>

Production Environment

tsx

<CopilotKit
  runtimeUrl="https://your-app.com/api/copilotkit"
  publicApiKey={process.env.NEXT_PUBLIC_COPILOTKIT_API_KEY}
  showDevConsole={false} // Hide from users
  onError={(errorEvent) => {
    // Production error observability
    if (errorEvent.type === "error") {
      // Log critical errors
      logger.error("CopilotKit Error", {
        error: errorEvent.error,
        context: errorEvent.context,
        timestamp: errorEvent.timestamp,
      });

      // Send to monitoring service
      monitoring.captureError(errorEvent.error, {
        extra: errorEvent.context,
      });
    }
  }}
>
</CopilotKit>

Getting Started with Copilot Cloud

To use error observability hooks, you'll need a Copilot Cloud account:

Sign up for free at https://cloud.copilotkit.ai
Get your public API key from the dashboard

Add it to your environment variables:

bash

NEXT_PUBLIC_COPILOTKIT_API_KEY=ck_pub_your_key_here

Use it in your CopilotKit provider:

tsx

<CopilotKit publicApiKey={process.env.NEXT_PUBLIC_COPILOTKIT_API_KEY}>
</CopilotKit>

<Callout type="info"> Copilot Cloud is free to get started and provides production-ready infrastructure for your AI copilots, including comprehensive error observability and monitoring capabilities. </Callout>

Best Practices

✅ Do

Use showDevConsole={true} during development for immediate feedback
Set showDevConsole={false} in production to hide errors from users
Implement proper error observability with the onError hook for monitoring
Monitor error patterns to identify and fix issues proactively
Use structured logging to make error analysis easier

❌ Don't

Don't expose detailed errors to end users in production
Don't ignore error events - they provide valuable debugging information
Don't log sensitive data in error observability hooks
Don't block the UI with error handling logic

Troubleshooting

Error Observability Not Working

If your onError hook isn't being called:

Check your publicApiKey - error observability requires a valid API key
Verify the key format - should start with ck_pub_
Ensure the key is set - check your environment variables
Test with dev console - use showDevConsole={true} to see if errors are occurring

Dev Console Not Showing

If the dev console isn't displaying errors:

Check showDevConsole setting - ensure it's set to true
Look for console errors - check browser dev tools for JavaScript errors
Verify error occurrence - make sure errors are actually happening

Next Steps

Learn about Copilot Cloud features
Explore the CopilotKit reference documentation
Check out troubleshooting guides for common issues