gabrielmoreira 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:
- 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. - Runtime mode -- Is this SSE mode (
CopilotSseRuntime) or Intelligence mode (CopilotIntelligenceRuntime)? Check the runtime constructor. - Transport configuration -- What is
runtimeUrlset to on theCopilotKitprovider (from@copilotkit/react-core/v2)? Does it match thebasePathincreateCopilotRuntimeHandler? - Agent type -- Is the agent a
BuiltInAgent,LangGraphAgent,A2AAgent, or customAbstractAgent? - Error messages -- Collect the exact error from browser console and server logs. CopilotKit uses structured error codes (see
references/error-patterns.md). - Browser network tab -- Check the
/inforequest (runtime discovery), the/agent/:id/runSSE 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 likeNETWORK_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 likeruntime_info_fetch_failed,agent_connect_failed,agent_run_failed. TranscriptionErrorCode-- Used by both v1 and v2 for voice transcription. Codes likeservice_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:
- RunStartedEvent -- Confirms the agent run was initiated
- TextMessageStartEvent / TextMessageChunkEvent / TextMessageEndEvent -- Text streaming
- ToolCallStartEvent / ToolCallArgsEvent / ToolCallEndEvent -- Tool invocations
- ToolCallResultEvent -- Tool results flowing back
- StateSnapshotEvent / StateDeltaEvent -- Agent state synchronization
- ReasoningStartEvent / ReasoningMessageContentEvent / ReasoningMessageEndEvent -- Reasoning tokens (can cause stalls, see issue #3323)
- RunFinishedEvent -- Successful completion
- 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 streamingreferences/agent-debugging.md-- Agent discovery, state sync, tool execution, AG-UI protocolreferences/error-patterns.md-- Complete error code catalog with resolutionsreferences/quick-workflows.md-- Step-by-step diagnostic sequences for common scenarios
Step 5: Fix and Verify
- Apply the fix
- Verify the
/infoendpoint returns the expected agent list - Confirm the SSE stream produces a complete event sequence (RunStarted through RunFinished)
- 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-issueshttps://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 |