Error message reference

This page lists the error strings CopilotKit surfaces in your console, network responses, and error UI. If you hit an error, search this page with Cmd/Ctrl-F for a distinctive phrase from the message.

For the programmatic onError codes (runtime_info_fetch_failed, tool_handler_failed, ...) rather than these human-readable strings, see Error Debugging.

Missing runtime configuration#

Error string:

Missing required prop: 'runtimeUrl' or 'publicApiKey' or 'publicLicenseKey'

Where: the v2 provider, <CopilotKitProvider>, imported from @copilotkit/react-core/v2. In production (NODE_ENV === "production") it's a thrown Error; in development it's a console.warn so local-agent and test setups still run.

Cause: the provider has no way to reach an agent. You didn't pass a runtimeUrl, a Copilot Cloud key (publicApiKey / publicLicenseKey), and you didn't register any local agents.

Fix (v2): provide one of these values to CopilotKitProvider, imported from @copilotkit/react-core/v2:

// Runtime-backed (recommended)
<CopilotKitProvider runtimeUrl="/api/copilotkit">{children}</CopilotKitProvider>

// Copilot Cloud
<CopilotKitProvider publicApiKey="ck_pub_...">{children}</CopilotKitProvider>

// Agents you manage yourself (v2 only)
<CopilotKitProvider selfManagedAgents={{ "my-agent": myAgent }}>{children}</CopilotKitProvider>

See Self-managed agents for the local-agent path.

Agent discovery failed#

Error name:

CopilotKitAgentDiscoveryError

This is the error name (error.name). The accompanying message is one of:

• Agent '<name>' was not found. Available agents are: <list>. Please verify the agent name in your configuration and ensure it matches one of the available agents.
• The requested agent was not found. Available agents are: <list>. ...
• Agent '<name>' was not found. Please set up at least one agent before proceeding. (when no agents are registered)

Cause: the frontend asked for an agentId that the runtime didn't return from its /info discovery. This is usually a typo, a missing registration, or a runtime that has no agents at all. The prebuilt components default to the agent named "default".

Fix:

• Register the agent under the id you're requesting (or under "default" if you pass no agentId):

  new CopilotRuntime({ agents: { default: myAgent } });

• Confirm the id matches the "Available agents" list in the message.
• Verify the runtime is reachable by hitting GET {runtimeUrl}/info directly (see Runtime HTTP endpoints). A discovery failure here cascades into this error.

CopilotKitAgentDiscoveryError is a banner error. It renders as a fixed banner in the dev console rather than a dismissible toast.

Agent route returned 404#

Error strings:

Agent not found
Agent '<id>' does not exist

Where: an HTTP 404 JSON body from the runtime's agent routes:

{ "error": "Agent not found", "message": "Agent 'my-agent' does not exist" }

Cause: a POST /agent/:agentId/run, /connect, or /stop/:threadId request named an agentId that isn't registered on the runtime. This is the server-side counterpart to the client-side CopilotKitAgentDiscoveryError.

Fix: register the agent under that key in new CopilotRuntime({ agents: { ... } }). If you see this on the /connect route before sending any message, also read the /connect 404 entry.

Agent run failed#

Error string:

Failed to run agent

Where: a 500 JSON body from the runtime's run/connect routes, with a message field carrying the underlying error.

Cause: the agent threw while executing. Common causes include a bad model string, a missing API key on the server, a provider error, or an exception inside the agent itself.

Fix: read the message field and check your server logs (the runtime logs the error name, message, and stack). Common culprits: an unset OPENAI_API_KEY (or equivalent) on the server, or a model string the provider doesn't recognize.

Capability discovery failed#

Error string:

Failed to fetch capabilities for agent "<name>"

Where: logged on the client when capability discovery for an agent fails.

Cause: the runtime couldn't be reached, or the named agent's capabilities endpoint errored.

Fix: confirm runtimeUrl is correct and the runtime is up; verify GET {runtimeUrl}/info returns the agent. See Common Issues: Network errors.

Related#

• Error Debugging: the onError callback and its programmatic error codes.
• Common Issues: network, endpoint, and tunnel problems.
• Runtime HTTP endpoints: probing /info and the agent routes with curl.