Menu
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.
| 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.0 |
Invoke this skill when:
Before proposing any fix, collect:
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.CopilotSseRuntime) or Intelligence mode (CopilotIntelligenceRuntime)? Check the runtime constructor.runtimeUrl set to in CopilotKitProvider? Does it match the basePath in createCopilotEndpoint?BuiltInAgent, LangGraphAgent, A2AAgent, or custom AbstractAgent?references/error-patterns.md)./info request (runtime discovery), the /agent/:id/run SSE stream, and any CORS preflight failures.CopilotKit has three error code systems:
@copilotkit/runtime). Codes like NETWORK_ERROR, AGENT_NOT_FOUND, API_NOT_FOUND. Still surfaced in some contexts since @copilotkit/* packages wrap v2 internally.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.
For streaming/agent issues, trace the AG-UI event flow:
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.
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/info endpoint returns the expected agent listDuring 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).
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"
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| Component | Path |
|---|---|
| V1 Error classes & codes | packages/v1/shared/src/utils/errors.ts |
| V2 Core error codes | packages/v2/core/src/core/core.ts (CopilotKitCoreErrorCode enum) |
| V2 Transcription errors | packages/v2/shared/src/transcription-errors.ts |
| Runtime SSE response | packages/v2/runtime/src/handlers/shared/sse-response.ts |
| Runtime info endpoint | packages/v2/runtime/src/handlers/get-runtime-info.ts |
| Runtime CORS config | packages/v2/runtime/src/endpoints/hono.ts |
| Intelligence platform client | packages/v2/runtime/src/intelligence-platform/client.ts |
| Agent package (BuiltInAgent) | packages/v2/agent/src/index.ts |
| Web Inspector | packages/v2/web-inspector/src/index.ts |
Use when adding CopilotKit to an existing project or bootstrapping a new CopilotKit project from scratch. Covers framework detection, package installation, runtime wiring, provider setup, and first working chat integration.
Use when building custom agent backends, implementing the AG-UI protocol, debugging streaming issues, or understanding how agents communicate with frontends. Covers event types, SSE transport, AbstractAgent/HttpAgent patterns, state synchronization, tool calls, and human-in-the-loop flows.
Use when contributing to the CopilotKit open-source project — forking, cloning, setting up the monorepo, creating branches, running tests, and submitting pull requests against CopilotKit/CopilotKit.
Use when building AI-powered features with CopilotKit v2 -- adding chat interfaces, registering frontend tools, sharing application context with agents, handling agent interrupts, and working with the CopilotKit runtime.
Use when wiring an external agent framework (LangGraph, CrewAI, PydanticAI, Mastra, ADK, LlamaIndex, Agno, Strands, Microsoft Agent Framework, or others) into a CopilotKit application via the AG-UI protocol.
Use when migrating a CopilotKit v1 application to v2 -- updating package imports, replacing deprecated hooks and components, switching from GraphQL runtime to AG-UI protocol runtime, and resolving breaking API changes.