Copilotkit Debug

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 @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 createCopilotEndpoint? 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:

[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

Agent Debugging Reference

Agent Types in CopilotKit v2

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:

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

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

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

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

   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.5", "anthropic/claude-opus-4"
• "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:

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 the Intelligence platform
• 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

Enable it during development:

import { CopilotKitWebInspector } from "@copilotkit/web-inspector";

<CopilotKit runtimeUrl="/api/copilotkit">
  <CopilotKitWebInspector />
  <YourApp />
</CopilotKit>;

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/v1/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 createCopilotEndpoint() 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.

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/v1/shared/src/utils/errors.ts:

---

V2 Error Codes (CopilotKitCoreErrorCode)

Used by @copilotkit/core. Defined in packages/v2/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. Defined in packages/v2/shared/src/transcription-errors.ts.

---

Intelligence Platform Error (PlatformRequestError)

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

---

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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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

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 createCopilotEndpoint({ 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

<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

npm ls @copilotkit/runtime @copilotkit/react @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)

Default CORS allows all origins without credentials. If you need credentials:

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

And on the client:

<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

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:

Step 5: Check the agent's model string

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

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:

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

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

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) runs as a Hono HTTP server. It exposes these endpoints under the configured basePath:

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 CopilotKitIntelligence configuration with apiUrl, wsUrl, apiKey, tenantId.
• Agent runs are durable -- threads are persisted on the Intelligence platform.
• 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:

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

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

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

   // Server
   createCopilotEndpoint({ runtime, basePath: "/api/copilotkit" });

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

3. Check the Hono app mounting: If using a framework adapter (Next.js, Express), ensure the Hono app 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 no cors option is provided to createCopilotEndpoint, 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:

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

On the client side, enable credentials:

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

Common CORS Errors

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

{
  "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:

{
  "intelligence": {
    "wsUrl": "wss://api.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

<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

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.

Sources

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

error-patterns.md

• packages/v1/shared/src/utils/errors.ts (CopilotKitErrorCode enum, all v1 error classes: CopilotKitError, CopilotKitMisuseError, CopilotKitVersionMismatchError, CopilotKitApiDiscoveryError, CopilotKitRemoteEndpointDiscoveryError, CopilotKitAgentDiscoveryError, CopilotKitLowLevelError, ResolvedCopilotKitError, ConfigurationError, MissingPublicApiKeyError, UpgradeRequiredError)
• packages/v2/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/v2/shared/src/transcription-errors.ts (TranscriptionErrorCode enum)
• packages/v2/runtime/src/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/v2/runtime/src/ (CopilotRuntime, endpoint factories, route definitions, SSE streaming, /info endpoint response shape)
• packages/v2/runtime/src/endpoints/ (CORS configuration, Hono middleware, Express middleware)
• packages/v2/runtime/src/intelligence-platform/ (CopilotKitIntelligence, IntelligenceAgentRunner, WebSocket URLs)
• packages/v2/runtime/src/runner/ (InMemoryAgentRunner, AgentRunner abstract class)
• packages/v2/react/src/ (CopilotKit provider props: runtimeUrl, credentials, headers)
• GitHub issues: #3170, #3425

agent-debugging.md

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

quick-workflows.md

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