Stats
Actions
Tags
From copilotkit
Diagnoses CopilotKit runtime failures, agent connectivity issues, streaming errors, tool execution problems, transcription failures, and version mismatches. Traces AG-UI SSE events.
How this skill is triggered — by the user, by Claude, or both
Slash command
/copilotkit:copilotkit-debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Invoke this skill when:
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 on the CopilotKit provider (from @copilotkit/react-core/v2)? 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 |
npx claudepluginhub copilotkit/copilotkit --plugin copilotkitAdds CopilotKit to existing projects or bootstraps new ones. Detects framework, installs packages, wires runtime, and sets up first chat integration.
Diagnoses AgentCore agent failures including wrong answers, errors, timeouts, tool issues, and CLI problems by reading traces, logs, and checking prerequisites.
Systematic debugging for ADK agents — trace reading, log analysis, common failure diagnosis, and the debug loop.