copilotkit-debug

어떤 스킬인가요?

Use when diagnosing CopilotKit issues -- runtime connectivity failures, agent not responding, streaming errors, tool execution problems, transcription failures, version mismatches, and AG-UI event tracing.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Agent Debugging Reference

## Agent Types in CopilotKit v2

| Agent Type             | Package                  | Description                                                                          |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
| `BuiltInAgent`         | `@copilotkit/runtime/v2` | Uses Vercel AI SDK `streamText` with configurable model providers                    |
| `LangGraphAgent`       | `@ag-ui/langgraph`       | Wraps a LangGraph deployment (Python or JS)                                          |
| `A2AAgent`             | Varies                   | Agent-to-Agent protocol agent                                                        |
| Custom `AbstractAgent` | `@ag-ui/client`          | Any class extending `AbstractAgent` with a `run()` returning `Observable<BaseEvent>` |

## Agent Discovery Issues

### Agent Not Found

**Symptom**: `CopilotKitCoreErrorCode.agent_not_found` or `CopilotKitErrorCode.AGENT_NOT_FOUND`

**Diagnostic steps**:

1. Hit the `/info` endpoint to see registered agents:

   ```bash
   curl http://localhost:3001/api/copilotkit/info | jq .agents
   ```

2. Compare the agent names in the response with the `agentId` prop:

   ```tsx
   <CopilotChat agentId="myAgent" />;
   // or
   const { run } = useAgent({ name: "myAgent" });
   ```

3. Check the runtime agent map -- keys must match exactly (case-sensitive):

   ```ts
   new CopilotRuntime({
     agents: {
       myAgent: new BuiltInAgent({
         /* ... */
       }), // Key "myAgent" is the agent ID
     },
   });
   ```

4. If using lazy agent loading (`agents: Promise<...>`), check that the promise resolves successfully.

### Agent Constructor Failures

If an agent throws during construction, the runtime may start without it:

- **BuiltInAgent**: `resolveModel()` throws if the provider string is invalid (e.g., `"openai/"` without a model name, or `"unknown/model"`).
- **LangGraphAgent**: May fail if the LangGraph deployment URL is unreachable.
- **A2AAgent**: May fail if the A2A endpoint is misconfigured.

## AG-UI Event Tracing

### Event Flow for a Successful Run

```
RunStartedEvent
  -> TextMessageStartEvent (messageId)
  -> TextMessageChunkEvent (delta: "Hello")
  -> TextMessageChunkEvent (delta: " world")
  -> TextMessageEndEvent
RunFinishedEvent
```

### Event Flow with Tool Calls

```
RunStartedEvent
  -> TextMessageStartEvent
  -> TextMessageChunkEvent (delta: "Let me check...")
  -> TextMessageEndEvent
  -> ToolCallStartEvent (toolCallId, toolName)
  -> ToolCallArgsEvent (delta: '{"query": "weather"}')
  -> ToolCallEndEvent
  -> ToolCallResultEvent (result: '{"temp": 72}')
  -> TextMessageStartEvent
  -> TextMessageChunkEvent (delta: "The temperature is 72F")
  -> TextMessageEndEvent
RunFinishedEvent
```

### Event Flow with Errors

```
RunStartedEvent
  -> RunErrorEvent (message: "...")      // Non-fatal, run continues
  -> TextMessageStartEvent
  -> ...
RunFinishedEvent
```

Or for fatal errors:

```
RunStartedEvent
  -> RunErrorEvent (message: "...")      // Fatal
  // Stream ends without RunFinishedEvent
```

### Event Flow with State Sync

```
RunStartedEvent
  -> StateSnapshotEvent (snapshot: {...})    // Full state
  -> StateDeltaEvent (delta: [{op: "replace", path: "/count", value: 5}])
  -> TextMessageStartEvent
  -> ...
RunFinishedEvent
```

### Event Flow with Reasoning (Anthropic Extended Thinking)

```
RunStartedEvent
  -> ReasoningStartEvent
  -> ReasoningMessageStartEvent
  -> ReasoningMessageContentEvent (delta: "thinking...")
  -> ReasoningMessageEndEvent
  -> ReasoningEndEvent
  -> TextMessageStartEvent
  -> TextMessageChunkEvent
  -> TextMessageEndEvent
RunFinishedEvent
```

**Known issue**: Reasoning events can cause stalls if the client-side event handler does not consume them properly (issue #3323).

## State Synchronization Issues

### State Not Updating on Frontend

**Symptom**: Agent emits `StateSnapshotEvent` or `StateDeltaEvent` but the React component does not re-render.

**Diagnostic steps**:

1. Verify the agent is emitting state events -- check the SSE stream in the Network tab.
2. If using `useFrontendTool` with state, ensure the state shape matches what the component expects.
3. For LangGraph agents: verify `copilotkit_emit_state` events are reaching the frontend (see Python SDK event prefix mismatch, issue #3519).

### Context Not Reaching Agents

**Symptom**: Agent does not receive application context set via `useAgentContext` or similar hooks.

**Diagnostic steps**:

1. Context is sent as `forwardedProps` in the AG-UI `RunAgentInput`. Check the request body to `/agent/:id/run`.
2. For Mastra agents: context propagation through the middleware chain may not work correctly (issue #3426).
3. Verify that `useAgentContext` is called inside the `CopilotKit` provider tree (from `@copilotkit/react-core/v2`) and before the agent runs.

## Tool Execution Issues

### Frontend Tool Not Found

**Error code**: `tool_not_found`

The agent called a tool name that does not match any registered frontend tool.

**Diagnostic steps**:

1. List registered tools by checking the AG-UI `Tool[]` array in the request to `/agent/:id/run`.
2. Ensure `useFrontendTool` is registered with the exact tool name (case-sensitive).
3. The tool must be registered BEFORE the agent run starts -- if it is registered lazily after mount, a race condition can occur.

### Tool Arguments Parse Failed

**Error code**: `tool_argument_parse_failed`

The LLM generated arguments that do not match the tool's parameter schema.

**Diagnostic steps**:

1. Check the `ToolCallArgsEvent` in the SSE stream -- the `delta` field contains the raw JSON.
2. Validate the JSON against the tool's schema (Zod or JSON Schema).
3. This is usually an LLM issue -- consider improving the tool description or parameter descriptions.
4. For Zod schema validation issues in backend actions, see issue #3198.

### Tool Handler Threw an Error

**Error code**: `tool_handler_failed`

The tool's `execute` function threw an exception.

**Diagnostic steps**:

1. Check the browser console for the error.
2. The `onError` callback in `CopilotChat` or the `CopilotKit` provider receives the error with context.
3. Wrap the tool handler in try/catch for better error reporting.

### Tool Call Succeeds But Agent Does Not Continue

**Symptom**: The tool returns a result but the agent does not produce a follow-up message.

**Diagnostic steps**:

1. Check that `ToolCallResultEvent` was emitted in the SSE stream after the tool completed.
2. For Human-in-the-Loop tools: the `runId` may change after HITL resolve (issue #3456), breaking the continuation.
3. For mixed frontend/backend tools: OpenAI may reject the request if tool definitions conflict (issue #3424).

## BuiltInAgent-Specific Issues

### Model Resolution Failures

`BuiltInAgent` uses `resolveModel()` to convert string identifiers to Vercel AI SDK `LanguageModel` instances.

Supported formats:

- `"openai/gpt-5"`, `"openai/gpt-4o"`, `"openai/o3-mini"`
- `"anthropic/claude-sonnet-4-6"`, `"anthropic/claude-opus-4-8"`
- `"google/gemini-2.5-pro"`, `"google/gemini-2.5-flash"`
- `"vertex/gemini-2.5-pro"` (uses Google Vertex AI)

Common errors:

- `Invalid model string "..."` -- Missing provider prefix or model name
- `Unknown provider "..." in "..."` -- Unsupported provider (only openai, anthropic, google, vertex)
- Missing API key -- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY` not set in environment

### MCP Client Integration

`BuiltInAgent` supports MCP (Model Context Protocol) clients:

```ts
new BuiltInAgent({
  model: "openai/gpt-4o",
  mcpClients: [
    { type: "http", url: "http://localhost:8080" },
    {
      type: "sse",
      url: "http://localhost:8081/sse",
      headers: { Authorization: "Bearer ..." },
    },
  ],
});
```

MCP debugging:

- `type: "http"` uses `StreamableHTTPClientTransport`
- `type: "sse"` uses `SSEClientTransport`
- If the MCP server is unreachable, the agent may fail silently or throw during tool discovery
- Check the MCP server logs for incoming connection attempts

## LangGraph Agent Issues

### Python SDK Event Name Mismatch

The CopilotKit Python SDK (v0.1.83) dispatches custom events with a `"copilotkit_"` prefix, but `ag-ui-langgraph` expects event names without that prefix. This causes `copilotkit_emit_message`, `copilotkit_emit_state`, and `copilotkit_emit_tool_call` to be silently dropped (issue #3519).

### LangGraph JS Template Outdated

The official LangGraph JS template may be outdated and incompatible with current CopilotKit versions (issue #3231). Check for the latest template version.

## Intelligence Mode Specific Issues

### Thread Operations

Intelligence mode uses the `CopilotKitIntelligence` client to manage threads:

- **409 Conflict on createThread**: Another request created the thread between get and create. Handled automatically by `getOrCreateThread`.
- **404 on getThread**: Thread does not exist. The client will create a new one.
- **Auth failures (401)**: Invalid `apiKey` or `tenantId` in the Intelligence configuration.

### WebSocket Connection Issues

Intelligence mode uses WebSocket for real-time events:

- Runner WebSocket: `{wsUrl}/runner` -- used by the runtime to communicate with CopilotKit Intelligence
- Client WebSocket: `{wsUrl}/client` -- used by the frontend for real-time thread updates

If WebSocket connections fail:

1. Check that the `wsUrl` is correct (should start with `wss://`)
2. Verify the API key and tenant ID
3. Check for WebSocket-blocking proxies or firewalls
4. The URLs are auto-derived from the base `wsUrl` -- `/runner` and `/client` suffixes are appended automatically

## Web Inspector

The CopilotKit Web Inspector (`@copilotkit/web-inspector`) provides real-time visibility into:

- AG-UI events as they flow
- Error events with error codes
- Agent state snapshots
- Tool call lifecycle

It mounts itself. React, Vue, and Angular all depend on
`@copilotkit/web-inspector` and mount `cpk-web-inspector` from their provider,
so there is nothing to import and nothing to render:

```tsx
<CopilotKitProvider runtimeUrl="/api/copilotkit">
  <YourApp />
</CopilotKitProvider>
```

Visibility is decided by `shouldEnableInspector` in `@copilotkit/shared`:
`isBrowser && isDevelopment && enableInspector !== false`. All three must hold,
so `enableInspector` is an **opt-out** — setting it to `true` cannot add the
Inspector to a production build.

```tsx
<CopilotKitProvider runtimeUrl="/api/copilotkit" enableInspector={false}>
```

Vue uses the kebab-case prop `:enable-inspector="false"`; Angular configures it
through `provideCopilotKit({ enableInspector: false })`.

There is no `CopilotKitWebInspector` React component — `@copilotkit/web-inspector`
exports the custom-element tag (`WEB_INSPECTOR_TAG`), not a wrapper.

# CopilotKit Error Pattern Catalog

## V1 Error Codes (`CopilotKitErrorCode`)

Legacy error codes from the v1 runtime layer. These still surface in `@copilotkit/*` packages since they wrap v2 internally. Defined in `packages/shared/src/utils/errors.ts`.

### NETWORK_ERROR

- **HTTP Status**: 503
- **Severity**: CRITICAL (banner)
- **Cause**: Server unreachable, DNS failure, connection timeout, SSL/TLS issues
- **Resolution**: Verify the runtime server is running and accessible. Check `runtimeUrl` on the `CopilotKit` provider (from `@copilotkit/react-core/v2`). Common sub-causes:
  - `ECONNREFUSED` -- Server not running on the expected port
  - `ENOTFOUND` -- DNS cannot resolve the hostname
  - `ETIMEDOUT` -- Server overloaded or network issues
- **Docs**: https://docs.copilotkit.ai/troubleshooting/common-issues#i-am-getting-a-network-errors--api-not-found

### NOT_FOUND

- **HTTP Status**: 404
- **Severity**: CRITICAL (banner)
- **Cause**: The runtime URL returns 404. Wrong basePath or the server is not serving CopilotKit at that path.
- **Resolution**: Ensure `basePath` in `createCopilotRuntimeHandler()` matches the `runtimeUrl` in the provider.
- **Docs**: https://docs.copilotkit.ai/troubleshooting/common-issues#i-am-getting-a-network-errors--api-not-found

### AGENT_NOT_FOUND

- **HTTP Status**: 500
- **Severity**: CRITICAL (banner)
- **Cause**: The requested agent name does not exist in the runtime's agent registry.
- **Resolution**: Verify the agent name matches between `CopilotChat agentId` and the runtime's `agents` map. The error message lists available agents.
- **Docs**: https://docs.copilotkit.ai/coagents/troubleshooting/common-issues#i-am-getting-agent-not-found-error

### API_NOT_FOUND

- **HTTP Status**: 404
- **Severity**: CRITICAL (banner)
- **Cause**: The CopilotKit API endpoint itself cannot be discovered. Usually a routing/basePath mismatch.
- **Resolution**: Check that the runtime's Hono/Express app is mounted at the correct path. The error includes the URL that failed.
- **Docs**: https://docs.copilotkit.ai/troubleshooting/common-issues#i-am-getting-a-network-errors--api-not-found

### REMOTE_ENDPOINT_NOT_FOUND

- **HTTP Status**: 404
- **Severity**: CRITICAL (banner)
- **Cause**: A remote endpoint specified in the runtime configuration cannot be contacted.
- **Resolution**: Verify the remote endpoint URL is correct and the service is running. Check firewall/network rules.
- **Docs**: https://docs.copilotkit.ai/troubleshooting/common-issues#i-am-getting-copilotkits-remote-endpoint-not-found-error

### AUTHENTICATION_ERROR

- **HTTP Status**: 401
- **Severity**: CRITICAL (banner)
- **Cause**: Authentication failed when contacting the runtime or a remote service.
- **Resolution**: Check API keys, tokens, and authentication headers.
- **Docs**: https://docs.copilotkit.ai/troubleshooting/common-issues#authentication-errors

### VERSION_MISMATCH

- **HTTP Status**: 400
- **Severity**: INFO (dev only)
- **Cause**: `@copilotkit/*` packages are on different versions.
- **Resolution**: Ensure all `@copilotkit/*` packages are the same version. Run `npm ls @copilotkit/runtime @copilotkit/react-core`.

### CONFIGURATION_ERROR

- **HTTP Status**: 400
- **Severity**: WARNING (banner)
- **Cause**: Invalid runtime or provider configuration.
- **Resolution**: Review the CopilotRuntime and `CopilotKit` provider configuration.

### MISSING_PUBLIC_API_KEY_ERROR

- **HTTP Status**: 400
- **Severity**: CRITICAL (banner)
- **Cause**: No public key is set on the `CopilotKit` provider (from `@copilotkit/react-core/v2`) when using CopilotKit Intelligence (the hosted platform). The canonical prop is `publicLicenseKey`; `publicApiKey` is a deprecated alias.
- **Resolution**: Add `publicLicenseKey` to the provider, or switch to self-hosted mode with `runtimeUrl`.

### UPGRADE_REQUIRED_ERROR

- **HTTP Status**: 402
- **Severity**: WARNING (banner)
- **Cause**: The current plan does not support the requested feature.
- **Resolution**: Upgrade the CopilotKit plan or remove the feature flag.

### MISUSE

- **HTTP Status**: 400
- **Severity**: WARNING (dev only)
- **Cause**: Incorrect API usage detected at development time (e.g., using a hook outside its provider).
- **Resolution**: Follow the error message guidance -- typically a component is being used outside the required provider.

### UNKNOWN

- **HTTP Status**: 500
- **Severity**: CRITICAL (toast)
- **Cause**: Unclassified server error.
- **Resolution**: Check server logs for the underlying exception.

---

## V1 Error Classes

All defined in `packages/shared/src/utils/errors.ts`:

| Class                                    | Extends                       | When Thrown                               |
| ---------------------------------------- | ----------------------------- | ----------------------------------------- |
| `CopilotKitError`                        | `GraphQLError`                | Base class for all structured errors      |
| `CopilotKitMisuseError`                  | `CopilotKitError`             | Wrong usage of components/hooks           |
| `CopilotKitVersionMismatchError`         | `CopilotKitError`             | Package version incompatibility           |
| `CopilotKitApiDiscoveryError`            | `CopilotKitError`             | Runtime endpoint not found (404, routing) |
| `CopilotKitRemoteEndpointDiscoveryError` | `CopilotKitApiDiscoveryError` | Remote agent endpoint unreachable         |
| `CopilotKitAgentDiscoveryError`          | `CopilotKitError`             | Named agent not in registry               |
| `CopilotKitLowLevelError`                | `CopilotKitError`             | Pre-HTTP errors (DNS, connection refused) |
| `ResolvedCopilotKitError`                | `CopilotKitError`             | HTTP error responses (status-code based)  |
| `ConfigurationError`                     | `CopilotKitError`             | Invalid configuration                     |
| `MissingPublicApiKeyError`               | `ConfigurationError`          | Intelligence (hosted) mode without key    |
| `UpgradeRequiredError`                   | `ConfigurationError`          | Plan limitation                           |

---

## V2 Error Codes (`CopilotKitCoreErrorCode`)

Used by `@copilotkit/core`. Defined in `packages/core/src/core/core.ts`. These are emitted via the `onError` subscriber callback.

### runtime_info_fetch_failed

- **Cause**: The `/info` endpoint returned an error or was unreachable.
- **Resolution**: Verify `runtimeUrl` points to a running CopilotRuntime. Check CORS if cross-origin. The `/info` endpoint must return agent metadata and runtime version.

### agent_connect_failed

- **Cause**: WebSocket or HTTP connection to the agent failed during the connect phase.
- **Resolution**: For Intelligence mode, verify the WebSocket URL (`wsUrl`) is correct. For SSE mode, check that the agent exists in the runtime.

### agent_run_failed

- **Cause**: The agent run threw an exception before completing.
- **Resolution**: Check server-side logs for the agent execution error. Common causes: missing API keys for the LLM provider, invalid model configuration.

### agent_run_failed_event

- **Cause**: The AG-UI stream contained a `RunFailedEvent` (the agent explicitly signaled failure).
- **Resolution**: The event payload contains the failure reason. Check the agent's implementation for error handling.

### agent_run_error_event

- **Cause**: The AG-UI stream contained a `RunErrorEvent` (non-fatal error during the run).
- **Resolution**: Check the error message in the event. May be transient -- the agent might recover.

### tool_argument_parse_failed

- **Cause**: The JSON arguments for a frontend tool call could not be parsed.
- **Resolution**: Check the tool's parameter schema. The LLM may have generated malformed JSON.

### tool_handler_failed

- **Cause**: A frontend tool's `execute` handler threw an exception.
- **Resolution**: Check the tool's handler code. The error is caught and reported via `onError`.

### tool_not_found

- **Cause**: The agent called a tool that is not registered in the frontend.
- **Resolution**: Ensure `useFrontendTool` is registered with the correct name before the agent runs.

### agent_not_found

- **Cause**: The `agentId` passed to `CopilotChat` or `useAgent` does not match any agent in the runtime.
- **Resolution**: Check the runtime's `/info` endpoint to see available agents. Match the `agentId` prop.

### transcription_failed

- **Cause**: Generic transcription failure.
- **Resolution**: See TranscriptionErrorCode section below for specific sub-codes.

### transcription_service_not_configured

- **Cause**: Voice transcription requested but no `transcriptionService` configured in the runtime.
- **Resolution**: Add a transcription service to the runtime constructor.

### transcription_invalid_audio

- **Cause**: Audio format not supported by the transcription provider.
- **Resolution**: Check supported audio formats (typically webm, wav, mp3).

### transcription_rate_limited

- **Cause**: Transcription provider rate limit exceeded.
- **Resolution**: Wait and retry. Consider caching or reducing request frequency.

### transcription_auth_failed

- **Cause**: Authentication with the transcription provider failed.
- **Resolution**: Check the transcription API key configuration.

### transcription_network_error

- **Cause**: Network error during transcription API call.
- **Resolution**: Check connectivity to the transcription provider.

---

## Transcription Error Codes (`TranscriptionErrorCode`)

Used by `@copilotkit/shared` and `@copilotkit/react-core`. Defined in `packages/shared/src/transcription-errors.ts`.

| Code                     | Retryable | Description                                 |
| ------------------------ | --------- | ------------------------------------------- |
| `service_not_configured` | No        | No transcription service in runtime         |
| `invalid_audio_format`   | No        | Unsupported audio format                    |
| `audio_too_long`         | No        | Audio file exceeds maximum duration         |
| `audio_too_short`        | No        | Audio too short to transcribe               |
| `rate_limited`           | Yes       | Provider rate limit hit                     |
| `auth_failed`            | No        | Provider authentication failed              |
| `provider_error`         | Yes       | Provider returned an error                  |
| `network_error`          | Yes       | Network failure during transcription        |
| `invalid_request`        | No        | Malformed request to transcription endpoint |

---

## Intelligence Error (`PlatformRequestError`)

Used by `@copilotkit/runtime` for Intelligence mode. Defined in `packages/runtime/src/v2/runtime/intelligence-platform/client.ts`.

| Status | Meaning                                                                                |
| ------ | -------------------------------------------------------------------------------------- |
| 404    | Thread not found                                                                       |
| 409    | Thread already exists (race condition -- handled automatically by `getOrCreateThread`) |
| 401    | Invalid API key or tenant ID                                                           |
| 500    | Platform server error                                                                  |

---

## Common GitHub-Reported Issues

These are frequently reported bugs from the CopilotKit issue tracker:

### Event Name Prefix Mismatch (Python SDK + ag-ui-langgraph)

- **Issue**: [#3519](https://github.com/CopilotKit/CopilotKit/issues/3519)
- **Symptom**: `copilotkit_emit_message`, `copilotkit_emit_state`, `copilotkit_emit_tool_call` never reach the frontend
- **Cause**: Python SDK dispatches events with `"copilotkit_"` prefix but `ag-ui-langgraph` expects names without the prefix
- **Resolution**: Update `ag-ui-langgraph` or patch the event name mapping

### Tool Call Failing Silently

- **Issue**: [#3510](https://github.com/CopilotKit/CopilotKit/issues/3510)
- **Symptom**: `defineTool` tool calls fail without error or response
- **Resolution**: Check tool parameter schema validation and network responses

### Reasoning Events Cause Agent Stall

- **Issue**: [#3323](https://github.com/CopilotKit/CopilotKit/issues/3323)
- **Symptom**: Agent stalls permanently after Anthropic reasoning/thinking tokens
- **Cause**: `REASONING_*` events in the AG-UI SSE stream are not handled correctly
- **Resolution**: Update to a version with reasoning event handling fixes

### HITL Frontend Tool Not Executing After Confirmation

- **Issue**: [#3442](https://github.com/CopilotKit/CopilotKit/issues/3442)
- **Symptom**: `useFrontendTool` with `renderAndWaitForResponse` does not execute after user confirms
- **Resolution**: Check the HITL flow implementation and `runId` consistency (related: #3456)

### Authorization Header Not Passed to A2A Agents

- **Issue**: [#3170](https://github.com/CopilotKit/CopilotKit/issues/3170)
- **Symptom**: Auth headers from the client do not reach agents using A2A protocol
- **Resolution**: Verify header forwarding configuration in runtime middleware

### LangChainAdapter Regression ("Unknown provider undefined")

- **Issue**: [#3217](https://github.com/CopilotKit/CopilotKit/issues/3217)
- **Symptom**: `LangChainAdapter` throws "Unknown provider undefined" in v1.50.0+
- **Cause**: Custom adapters without `provider`/`model` properties hit a code path that assumes they exist
- **Resolution**: Migrate to v2 `BuiltInAgent` or add `.provider`/`.model` to the adapter

### Mixed Frontend and Backend Tool Execution Fails

- **Issue**: [#3424](https://github.com/CopilotKit/CopilotKit/issues/3424)
- **Symptom**: OpenAI `BadRequestError` when mixing frontend and backend tools with LangGraph
- **Resolution**: Check tool registration and ensure tools are not duplicated across frontend and backend

### Context Not Updated with Mastra Integration

- **Issue**: [#3426](https://github.com/CopilotKit/CopilotKit/issues/3426)
- **Symptom**: Context state does not propagate to Mastra agents
- **Resolution**: Verify context is being passed through the runtime middleware chain

### Subscribe Null Reference in A2A/A2UI

- **Issue**: [#3429](https://github.com/CopilotKit/CopilotKit/issues/3429)
- **Symptom**: `Cannot read properties of null (reading 'subscribe')` during A2A integration
- **Resolution**: Check agent lifecycle and ensure proper initialization order

### IME Input Cleared on Mobile (v2)

- **Issue**: [#3318](https://github.com/CopilotKit/CopilotKit/issues/3318)
- **Symptom**: Typing with IME on mobile devices clears input in CopilotChat
- **Resolution**: Known v2 issue with controlled input handling during IME composition

### Message ID Collision with OpenAI-Compatible Providers

- **Issue**: [#3410](https://github.com/CopilotKit/CopilotKit/issues/3410)
- **Symptom**: All messages share the same ID when using `@ai-sdk/openai-compatible`
- **Cause**: Default message ID from the compatible provider is not unique
- **Resolution**: Update to a patched version or use the native OpenAI provider

# Quick Diagnostic Workflows

## Workflow: "Runtime Not Connecting"

The client shows a connection error, banner error, or the chat never loads.

### Step 1: Verify the runtime is running

```bash
curl -v http://localhost:3001/api/copilotkit/info
```

- **No response / connection refused** -> The server is not running. Start it.
- **404** -> The basePath is wrong. Check `createCopilotRuntimeHandler({ basePath })` vs the URL you are hitting.
- **500** -> The agent loading failed. Check server logs for the error.
- **200 with JSON** -> Runtime is up. Proceed to step 2.

### Step 2: Check the client configuration

```tsx
<CopilotKit runtimeUrl="/api/copilotkit">
```

- Does `runtimeUrl` match the runtime's basePath exactly?
- If cross-origin (e.g., runtime on port 3001, app on port 3000), is CORS configured?
- If using a proxy (Next.js rewrites, nginx), does the proxy preserve the full path?

### Step 3: Check browser network tab

1. Look for the GET request to `/info`
2. If it is blocked by CORS, you will see a preflight OPTIONS failure
3. If it returns an error, the error body contains the `CopilotKitErrorCode`

### Step 4: Check package versions

```bash
npm ls @copilotkit/runtime @copilotkit/react-core @copilotkit/core @ag-ui/client
```

All `@copilotkit/*` packages should be the same version. Mismatches cause `VERSION_MISMATCH` errors.

### Step 5: Check CORS (if cross-origin)

With `cors: true`, the default CORS policy allows all origins without credentials. If you need credentials:

```ts
createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  cors: {
    origin: "https://your-frontend.com",
    credentials: true,
  },
});
```

And on the client:

```tsx
<CopilotKit
  runtimeUrl="https://your-api.com/api/copilotkit"
  credentials="include"
/>
```

---

## Workflow: "Agent Not Responding"

The chat connects but messages are never answered, or the agent returns an error.

### Step 1: Verify agent is registered

```bash
curl http://localhost:3001/api/copilotkit/info | jq '.agents'
```

Check that the agent name matches the `agentId` prop in `CopilotChat` or `useAgent`.

### Step 2: Check the SSE stream

1. Open browser DevTools > Network tab
2. Send a message in the chat
3. Find the POST to `/agent/:agentId/run`
4. Check the response:
   - **404** -> Agent not found in runtime
   - **500** -> Server error during agent execution
   - **200 with empty body** -> Agent started but produced no events
   - **200 with events** -> Check the events (step 3)

### Step 3: Inspect the event stream

Look at the SSE events in the response:

- **Only `RunStartedEvent` then nothing** -> Agent is stalled. Check server logs. Common causes:
  - Missing LLM API key (agent cannot call the model)
  - Agent waiting for a tool result that never comes
  - Reasoning event stall (Anthropic models, issue #3323)

- **`RunErrorEvent` present** -> Read the error message. Common causes:
  - LLM API returned an error (rate limit, invalid key, model not found)
  - Agent code threw an exception

- **`RunFinishedEvent` without text messages** -> Agent completed but produced no output. Check the agent's prompt and logic.

### Step 4: Check LLM API key

For `BuiltInAgent`, verify the environment variable:

| Provider  | Environment Variable            |
| --------- | ------------------------------- |
| OpenAI    | `OPENAI_API_KEY`                |
| Anthropic | `ANTHROPIC_API_KEY`             |
| Google    | `GOOGLE_API_KEY`                |
| Vertex    | Application Default Credentials |

### Step 5: Check the agent's model string

```ts
new BuiltInAgent({
  model: "openai/gpt-4o", // Must be "provider/model-name"
});
```

Invalid model strings throw `Error: Invalid model string "..."` or `Error: Unknown provider "..."`.

### Step 6: Check server-side logs

The SSE response handler logs errors with full stack traces:

```
Error running agent: <error>
Error stack: <stack trace>
Error details: { name, message, cause }
```

---

## Workflow: "Streaming Failures"

The agent starts responding but the stream cuts off, duplicates events, or corrupts messages.

### Step 1: Check for premature stream termination

1. Look at the SSE response in the Network tab
2. Does it end with `RunFinishedEvent`? If not:
   - **Connection closed mid-stream** -> Hosting platform timeout (Vercel: 30s default, Railway: 5min). Consider using Intelligence mode for long-running agents.
   - **Error in the stream** -> Check for `RunErrorEvent` before the cutoff
   - **Client navigated away** -> Expected behavior, the `abort` signal cleaned up the stream

### Step 2: Check for event ordering issues

Events must follow a logical sequence:

- `TextMessageStart` before `TextMessageChunk` before `TextMessageEnd`
- `ToolCallStart` before `ToolCallArgs` before `ToolCallEnd`
- `RunStarted` at the beginning, `RunFinished` at the end

If events are out of order, the issue is in the agent's Observable implementation.

### Step 3: Check for duplicate events

If the same message appears multiple times:

- **Message ID collision** -> Check issue #3410 (OpenAI-compatible providers reusing IDs)
- **Agent re-running** -> The `runId` changed mid-conversation. Check for HITL issues (issue #3456).

### Step 4: Check for message corruption

If message content is garbled or mixed:

- **Model-specific issue** -> DeepSeek and some models produce malformed streaming chunks (issue #3351)
- **Encoding issue** -> Verify the SSE response has `Content-Type: text/event-stream` and is UTF-8

### Step 5: Check hosting platform limits

| Platform            | Default SSE Timeout    | Notes                                 |
| ------------------- | ---------------------- | ------------------------------------- |
| Vercel (Serverless) | 30s (Hobby), 60s (Pro) | Use Edge Runtime or Intelligence mode |
| Vercel (Edge)       | 30s                    | Better but still limited              |
| Railway             | 5 min                  | Usually sufficient                    |
| Render              | 5 min                  | Usually sufficient                    |
| Self-hosted         | No limit               | Depends on reverse proxy config       |

For long agent runs, consider:

- Intelligence mode (persisted threads, WebSocket updates)
- Increasing the platform timeout if possible
- Breaking the agent work into smaller runs

---

## Workflow: "Frontend Tool Not Working"

A frontend tool registered with `useFrontendTool` is not being called or not returning results.

### Step 1: Verify tool registration

Check that the tool is registered before the agent runs:

```tsx
useFrontendTool({
  name: "get_weather", // Must match exactly what the agent calls
  description: "Get weather",
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => {
    /* ... */
  },
});
```

### Step 2: Check the SSE stream for tool events

Look for `ToolCallStartEvent` in the SSE stream:

- **Not present** -> The agent decided not to call the tool. Check the tool description.
- **Present but no `ToolCallResultEvent`** -> The frontend did not respond. Check:
  - Is the component with `useFrontendTool` mounted?
  - Did the `execute` handler throw? (Check `tool_handler_failed` error)
  - Is the tool name an exact match (case-sensitive)?

### Step 3: Check tool argument parsing

If `tool_argument_parse_failed` error appears:

- The LLM generated arguments that do not match the Zod/JSON schema
- Check `ToolCallArgsEvent` for the raw arguments
- Consider relaxing the schema or improving parameter descriptions

### Step 4: Check HITL tool flow

For `renderAndWaitForResponse` tools:

- The tool renders UI and waits for user input
- If the tool does not execute after user confirmation, check issue #3442
- The `runId` may change after HITL resolve (issue #3456)

---

## Workflow: "Transcription Not Working"

Voice input fails or produces errors.

### Step 1: Check transcription service configuration

```ts
const runtime = new CopilotRuntime({
  agents: {
    /* ... */
  },
  transcriptionService: myTranscriptionService, // Must be provided
});
```

If not configured, the error code is `service_not_configured` (HTTP 503).

### Step 2: Check the `/info` response

```bash
curl http://localhost:3001/api/copilotkit/info | jq '.audioFileTranscriptionEnabled'
```

Should be `true`. If `false`, the transcription service is not configured.

### Step 3: Check browser microphone permissions

- The browser must grant microphone access
- `AudioRecorderError: "Microphone permission denied"` -> User denied permission
- `AudioRecorderError: "No microphone found"` -> No microphone hardware detected

### Step 4: Check transcription provider credentials

- `auth_failed` -> API key is invalid or expired
- `rate_limited` -> Too many requests, wait and retry
- `provider_error` -> Provider-side issue, check provider status page

### Step 5: Check audio format

- `invalid_audio_format` -> Browser sends unsupported format
- `audio_too_long` / `audio_too_short` -> Recording duration out of bounds

---

## Escalation Path

If the issue is unresolved after following these workflows:

1. **Check the CopilotKit GitHub Issues**: Search https://github.com/CopilotKit/CopilotKit/issues for your error message or symptom.

2. **Enable the Web Inspector**: Add `<CopilotKitWebInspector />` to capture detailed event traces.

3. **Collect a diagnostic bundle**:
   - Package versions (`npm ls @copilotkit/*`)
   - Runtime `/info` response
   - SSE stream capture (copy from Network tab)
   - Server-side error logs
   - Browser console errors

4. **File a GitHub issue**: https://github.com/CopilotKit/CopilotKit/issues/new with the diagnostic bundle.

5. **Reach out to the CopilotKit team**: Book time with the CopilotKit team via their Discord (https://discord.gg/copilotkit) or contact support for urgent production issues.

# Runtime Debugging Reference

## Runtime Architecture

CopilotKit v2 runtime (`@copilotkit/runtime`) exposes a fetch-native handler with these endpoints under the configured `basePath`:

| Endpoint                  | Method                | Purpose                                                        |
| ------------------------- | --------------------- | -------------------------------------------------------------- |
| `/info`                   | GET                   | Runtime discovery -- returns version, agent list, capabilities |
| `/agent/:agentId/run`     | POST                  | Start an agent run, returns SSE event stream                   |
| `/agent/:agentId/connect` | POST                  | Connect to an existing agent run (Intelligence mode)           |
| `/agent/:agentId/stop`    | POST                  | Stop a running agent                                           |
| `/transcribe`             | POST                  | Audio transcription                                            |
| `/threads`                | GET/POST/PATCH/DELETE | Thread management (Intelligence mode only)                     |

## Runtime Modes

### SSE Mode (`"sse"`)

- Default mode. Agent runs are ephemeral.
- Each `/agent/:id/run` request creates a new run and streams AG-UI events as SSE.
- Uses `InMemoryAgentRunner` by default.
- No thread persistence -- state lives only for the duration of the SSE connection.

### Intelligence Mode (`"intelligence"`)

- Requires a `CopilotKitIntelligence` instance. `apiKey` is the only required field --
  it identifies the organization and project on its own, so there is no org or tenant
  option to pass. `apiUrl` / `wsUrl` are optional overrides that default to the managed
  platform (`https://api.intelligence.copilotkit.ai` and
  `wss://realtime.intelligence.copilotkit.ai` -- two separate hosts, so `wsUrl` cannot be
  derived from `apiUrl` by swapping the scheme).
- Agent runs are durable -- threads are persisted on CopilotKit Intelligence.
- Uses `IntelligenceAgentRunner` which coordinates via WebSocket.
- Supports thread listing, archiving, deletion, and real-time updates.
- Requires `identifyUser` callback to resolve authenticated users.

## Connectivity Debugging

### "Runtime not found" / 404 Errors

1. **Verify the runtime is running**: Hit the `/info` endpoint directly:

   ```bash
   curl http://localhost:3001/api/copilotkit/info
   ```

   Expected response: JSON with `version`, `agents`, `mode` fields.

2. **Check basePath alignment**: The `basePath` in `createCopilotRuntimeHandler()` must match the `runtimeUrl` on the `CopilotKit` provider (from `@copilotkit/react-core/v2`):

   ```ts
   // Server
   createCopilotRuntimeHandler({ runtime, basePath: "/api/copilotkit" });

   // Client
   <CopilotKit runtimeUrl="/api/copilotkit">
   ```

3. **Check the framework mounting**: Ensure the fetch handler is mounted at the right path. The framework's route path combined with `basePath` must form the full URL.

4. **Proxy/reverse proxy issues**: If running behind nginx, Vercel, or similar, ensure the proxy passes the full path and does not strip the prefix.

### Connection Refused (ECONNREFUSED)

- The runtime server is not running on the expected host:port.
- Check `process.env.PORT` or the server's listen configuration.
- If using Docker, ensure the port is exposed and the container is running.

### DNS Resolution Failed (ENOTFOUND)

- The hostname in `runtimeUrl` cannot be resolved.
- Check for typos in the URL.
- If using service discovery (Kubernetes, Docker Compose), verify the service name is correct.

### Timeout (ETIMEDOUT)

- Server is reachable but not responding in time.
- Check server load and resource limits.
- Increase timeout if the agent's first response takes a while (large model, cold start).

## CORS Debugging

### Default CORS Behavior

When `cors: true` is provided to `createCopilotRuntimeHandler`, the runtime defaults to:

- `origin: "*"` (all origins allowed)
- `credentials: false`
- All standard HTTP methods allowed
- All headers allowed

### CORS with Credentials (HTTP-only Cookies)

When using HTTP-only cookies for authentication, you must configure CORS explicitly:

```ts
createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  cors: {
    origin: "https://myapp.com", // Must be explicit, not "*"
    credentials: true,
  },
});
```

On the client side, enable credentials:

```tsx
<CopilotKit
  runtimeUrl="https://api.myapp.com/api/copilotkit"
  credentials="include"
/>
```

### Common CORS Errors

| Browser Error                                   | Cause                                    | Fix                                                                                           |
| ----------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| "No 'Access-Control-Allow-Origin' header"       | Runtime not sending CORS headers         | Verify `createCopilotRuntimeHandler` is handling the request (not a 404 from another handler) |
| "Credential is not supported if origin is '\*'" | `credentials: true` with wildcard origin | Set an explicit `origin` in the CORS config                                                   |
| "Method PUT is not allowed"                     | Preflight failure                        | Ensure the runtime's CORS allows the method (default config allows all)                       |
| CORS error only in production                   | Different origins in dev vs prod         | Update the `origin` config for the production domain                                          |

### Diagnosing CORS Issues

1. Open browser DevTools Network tab
2. Look for a failed OPTIONS (preflight) request to the runtime URL
3. Check the response headers -- `Access-Control-Allow-Origin`, `Access-Control-Allow-Credentials`, `Access-Control-Allow-Headers`
4. If no OPTIONS request appears, the browser may be making a "simple request" that still fails on the response headers

## SSE Streaming Debugging

### How SSE Works in CopilotKit

The `/agent/:agentId/run` endpoint returns an SSE response:

- Content-Type: `text/event-stream`
- Cache-Control: `no-cache`
- Connection: `keep-alive`

Events are encoded using `@ag-ui/encoder` (the `EventEncoder` class). Each event is a `data:` line in SSE format.

### Stream Never Starts

- **Agent not found**: The agent ID in the URL does not match any registered agent. Check the `/info` endpoint.
- **Middleware blocking**: A `beforeRequestMiddleware` might be throwing or returning an error response before the agent runs.
- **Agent constructor failure**: The agent's initialization might throw (e.g., missing API key). Check server-side logs.

### Stream Starts but Hangs

- **Agent waiting for tool result**: If the agent calls a frontend tool and the frontend does not respond, the stream will appear hung. Check that frontend tools are registered and responding.
- **Reasoning event stall**: Anthropic models with reasoning/thinking tokens can cause stalls if the event handler does not properly process `REASONING_*` events (issue #3323).
- **Backpressure**: If the client reads slowly, the `TransformStream` writer may block. This is rare with SSE but possible with very high event rates.

### Stream Ends Prematurely

- **Client disconnect**: If the browser tab is closed or the network drops, the `request.signal` aborts and the subscription is cleaned up.
- **Agent error**: An uncaught exception in the agent terminates the observable. Check for `RunErrorEvent` before the stream closes.
- **Server timeout**: Some hosting platforms (Vercel, Railway) have response timeouts. Long-running agent interactions may hit these limits.

### Debugging SSE in the Browser

1. Open DevTools > Network tab
2. Find the POST request to `/agent/:id/run`
3. Click the "EventStream" tab (Chrome) or check the Response tab for raw SSE data
4. Each event should be formatted as:

   ```
   data: {"type":"RunStarted","runId":"..."}

   data: {"type":"TextMessageStart","messageId":"..."}

   data: {"type":"TextMessageChunk","delta":"Hello"}
   ```

5. If events stop flowing, the issue is server-side (agent stalled or errored)

## Runtime Info Endpoint Debugging

The `/info` endpoint is the first request the client makes. If it fails, no agent interaction is possible.

### Expected Response Shape

```json
{
  "version": "1.52.0",
  "agents": {
    "myAgent": {
      "name": "myAgent",
      "description": "My agent description",
      "className": "BuiltInAgent"
    }
  },
  "audioFileTranscriptionEnabled": false,
  "mode": "sse",
  "a2uiEnabled": false
}
```

For Intelligence mode, the response also includes:

```json
{
  "intelligence": {
    "wsUrl": "wss://realtime.intelligence.copilotkit.ai/client"
  }
}
```

### Common `/info` Failures

- **500 error**: The `agents` promise rejected (lazy agent loading failed). Check the agents factory function.
- **404 error**: Wrong basePath or the runtime is not mounted at the expected URL.
- **CORS error**: The preflight for `/info` failed. See CORS section above.

## Custom Headers and Authentication

### Passing Headers from Client to Runtime

```tsx
<CopilotKit
  runtimeUrl="/api/copilotkit"
  headers={{ Authorization: `Bearer ${token}` }}
/>
```

Headers are sent with every request to the runtime, including `/info`, `/agent/:id/run`, etc.

### Accessing Headers in Middleware

```ts
const runtime = new CopilotRuntime({
  agents: {
    /* ... */
  },
  beforeRequestMiddleware: async ({ request }) => {
    const auth = request.headers.get("Authorization");
    // Validate auth, modify request, or throw to reject
    return request;
  },
});
```

### Header Forwarding to Agents

Headers from the client are available in the runtime middleware but are NOT automatically forwarded to remote agents (A2A). This is a known limitation (issue #3170 and #3425). To forward headers, use middleware to inject them into the agent configuration.

---
name: copilotkit-debug
description: "Use when diagnosing CopilotKit issues -- runtime connectivity failures, agent not responding, streaming errors, tool execution problems, transcription failures, version mismatches, and AG-UI event tracing."
version: 1.0.1
---

# CopilotKit Debugging Skill

## When to Use

Invoke this skill when:

- The CopilotKit runtime is unreachable or returning errors
- Agents fail to connect, respond, or stream events
- Frontend tools are not executing or returning results
- Transcription (voice) is failing
- Version mismatch errors appear between packages
- AG-UI SSE events are malformed or missing
- CORS errors block browser requests to the runtime

## Diagnostic Workflow

### Step 1: Gather Information

Before proposing any fix, collect:

1. **Package versions** -- Run `npm ls @copilotkit/runtime @copilotkit/react-core @copilotkit/core @ag-ui/client` (or the v1 equivalents). Version mismatches between runtime and React packages are a common root cause.
2. **Runtime mode** -- Is this SSE mode (`CopilotSseRuntime`) or Intelligence mode (`CopilotIntelligenceRuntime`)? Check the runtime constructor.
3. **Transport configuration** -- What is `runtimeUrl` set to on the `CopilotKit` provider (from `@copilotkit/react-core/v2`)? Does it match the `basePath` in `createCopilotRuntimeHandler`?
4. **Agent type** -- Is the agent a `BuiltInAgent`, `LangGraphAgent`, `A2AAgent`, or custom `AbstractAgent`?
5. **Error messages** -- Collect the exact error from browser console and server logs. CopilotKit uses structured error codes (see `references/error-patterns.md`).
6. **Browser network tab** -- Check the `/info` request (runtime discovery), the `/agent/:id/run` SSE stream, and any CORS preflight failures.

### Step 2: Check Logs and Error Codes

CopilotKit has three error code systems:

- **V1 error codes** -- Legacy error codes from the v1 runtime layer (`@copilotkit/runtime`). Codes like `NETWORK_ERROR`, `AGENT_NOT_FOUND`, `API_NOT_FOUND`. Still surfaced in some contexts since `@copilotkit/*` packages wrap v2 internally.
- **V2 `CopilotKitCoreErrorCode`** -- Used by `@copilotkit/core`. Codes like `runtime_info_fetch_failed`, `agent_connect_failed`, `agent_run_failed`.
- **`TranscriptionErrorCode`** -- Used by both v1 and v2 for voice transcription. Codes like `service_not_configured`, `rate_limited`, `auth_failed`.

Match the error code to the catalog in `references/error-patterns.md` for root cause and resolution.

### Step 3: Trace AG-UI Events

For streaming/agent issues, trace the AG-UI event flow:

1. **RunStartedEvent** -- Confirms the agent run was initiated
2. **TextMessageStartEvent / TextMessageChunkEvent / TextMessageEndEvent** -- Text streaming
3. **ToolCallStartEvent / ToolCallArgsEvent / ToolCallEndEvent** -- Tool invocations
4. **ToolCallResultEvent** -- Tool results flowing back
5. **StateSnapshotEvent / StateDeltaEvent** -- Agent state synchronization
6. **ReasoningStartEvent / ReasoningMessageContentEvent / ReasoningMessageEndEvent** -- Reasoning tokens (can cause stalls, see issue #3323)
7. **RunFinishedEvent** -- Successful completion
8. **RunErrorEvent** -- Agent-level error

Enable the CopilotKit Web Inspector (`@copilotkit/web-inspector`) to see events in real time. Or check the SSE stream directly in the browser Network tab -- each event is a `data:` line in the `text/event-stream` response.

### Step 4: Identify Root Cause

Use the reference documents to match symptoms to known issues:

- **`references/runtime-debugging.md`** -- Connectivity, CORS, transport, SSE streaming
- **`references/agent-debugging.md`** -- Agent discovery, state sync, tool execution, AG-UI protocol
- **`references/error-patterns.md`** -- Complete error code catalog with resolutions
- **`references/quick-workflows.md`** -- Step-by-step diagnostic sequences for common scenarios

### Step 5: Fix and Verify

1. Apply the fix
2. Verify the `/info` endpoint returns the expected agent list
3. Confirm the SSE stream produces a complete event sequence (RunStarted through RunFinished)
4. Check the browser console for any remaining structured errors

## Using mcp-docs for Live Documentation Lookups

During debugging, use the `copilotkit-docs` MCP server to look up the latest CopilotKit documentation. This server provides two tools: `search-docs` (search documentation) and `search-code` (search source code examples).

### MCP Setup

**Claude Code:** The MCP server is auto-configured by the plugin's `.mcp.json` -- no manual setup needed. The agent can call the `search-docs` and `search-code` tools from the `copilotkit-docs` server directly.

**Codex:** Add the following to your `.codex/config.toml`:

```toml
[mcp_servers.copilotkit-docs]
type = "http"
url = "https://mcp.copilotkit.ai/mcp"
```

### Tool Usage

The `search-docs` and `search-code` tools are invoked as MCP tool calls (not CLI commands). Examples of what to search for during debugging:

```
search-docs("AGENT_NOT_FOUND")
search-docs("CopilotRuntime configuration")
search-docs("AG-UI protocol events")
search-docs("troubleshooting common issues")
search-docs("CORS configuration copilotkit")
search-code("CopilotRuntime error handling")
```

The official troubleshooting docs are at:

- `https://docs.copilotkit.ai/troubleshooting/common-issues`
- `https://docs.copilotkit.ai/coagents/troubleshooting/common-issues`

## Key File Locations in the CopilotKit Codebase

| Component                      | Path                                                              |
| ------------------------------ | ----------------------------------------------------------------- |
| Legacy error classes & codes   | `packages/shared/src/utils/errors.ts`                             |
| V2 Core error codes            | `packages/core/src/core/core.ts` (`CopilotKitCoreErrorCode` enum) |
| V2 Transcription errors        | `packages/shared/src/transcription-errors.ts`                     |
| Runtime SSE response           | `packages/runtime/src/v2/runtime/handlers/shared/sse-response.ts` |
| Runtime info endpoint          | `packages/runtime/src/v2/runtime/handlers/get-runtime-info.ts`    |
| Runtime CORS config            | `packages/runtime/src/v2/runtime/core/fetch-cors.ts`              |
| CopilotKit Intelligence client | `packages/runtime/src/v2/runtime/intelligence-platform/client.ts` |
| BuiltInAgent                   | `packages/runtime/src/agent/index.ts`                             |
| Web Inspector                  | `packages/web-inspector/src/index.ts`                             |

# Sources

Files and directories read from CopilotKit/CopilotKit to generate this skill's references.
Generated: 2026-03-28

## error-patterns.md

- packages/shared/src/utils/errors.ts (CopilotKitErrorCode enum, all legacy v1 error classes: CopilotKitError, CopilotKitMisuseError, CopilotKitVersionMismatchError, CopilotKitApiDiscoveryError, CopilotKitRemoteEndpointDiscoveryError, CopilotKitAgentDiscoveryError, CopilotKitLowLevelError, ResolvedCopilotKitError, ConfigurationError, MissingPublicApiKeyError, UpgradeRequiredError)
- packages/core/src/core/core.ts (CopilotKitCoreErrorCode enum: runtime_info_fetch_failed, agent_connect_failed, agent_run_failed, tool_argument_parse_failed, tool_handler_failed, tool_not_found, agent_not_found, transcription error codes)
- packages/shared/src/transcription-errors.ts (TranscriptionErrorCode enum)
- packages/runtime/src/v2/runtime/intelligence-platform/client.ts (PlatformRequestError, HTTP status codes 404/409/401/500)
- GitHub issues: #3519, #3510, #3323, #3442, #3170, #3217, #3424, #3426, #3429, #3318, #3410

## runtime-debugging.md

- packages/runtime/src/v2/runtime/ (CopilotRuntime, endpoint factories, route definitions, SSE streaming, /info endpoint response shape)
- packages/runtime/src/v2/runtime/endpoints/ (CORS configuration, Hono middleware, Express middleware)
- packages/runtime/src/v2/runtime/intelligence-platform/ (CopilotKitIntelligence, IntelligenceAgentRunner, WebSocket URLs)
- packages/runtime/src/v2/runtime/runner/ (InMemoryAgentRunner, AgentRunner abstract class)
- packages/react-core/src/v2/ (`CopilotKit` provider props: runtimeUrl, credentials, headers)
- GitHub issues: #3170, #3425

## agent-debugging.md

- packages/runtime/src/agent/ (BuiltInAgent, resolveModel, model string formats, MCP client configuration)
- packages/runtime/src/v2/runtime/ (AgentRunner, agent registry, /info endpoint agent discovery)
- packages/core/src/ (CopilotKitCoreErrorCode, tool registry, onError subscriber)
- packages/react-core/src/v2/ (useFrontendTool, useAgent, CopilotChat agentId prop)
- packages/web-inspector/src/ (CopilotKitWebInspector component)
- GitHub issues: #3323, #3519, #3231, #3456, #3424, #3426, #3198

## quick-workflows.md

- packages/runtime/src/v2/runtime/ (endpoint route structure, /info endpoint, CORS defaults, SSE event flow)
- packages/runtime/src/agent/ (BuiltInAgent model string format, environment variable conventions)
- packages/core/src/ (error codes referenced in diagnostic steps)
- packages/react-core/src/v2/ (`CopilotKit` provider props, useFrontendTool registration, CopilotChat)
- packages/shared/src/ (TranscriptionErrorCode, transcription service configuration)
- packages/web-inspector/src/ (CopilotKitWebInspector for escalation)