# Error message reference

> Find the cause and fix for common CopilotKit console, network, and error UI messages.

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](/mastra/troubleshooting/error-debugging).

## Missing runtime configuration [#missing-runtime-configuration]

Error string:

```txt
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.

<Callout type="info" title="v1 behaves differently">
  The **v1** `<CopilotKit>` provider throws in **both development and
  production** when nothing is configured, whereas the v2 `<CopilotKitProvider>`
  only warns in development. Either way, registering `selfManagedAgents` or
  `agents__unsafe_dev_only` satisfies the check. No `runtimeUrl` or Copilot
  Cloud key is required.
</Callout>

**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`:

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

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

// Agents you manage yourself — the `selfManagedAgents` prop is also accepted by the v1 `<CopilotKit>` wrapper
<CopilotKitProvider selfManagedAgents={{ "my-agent": myAgent }}>{children}</CopilotKitProvider>
```

See [Self-managed agents](/mastra/backend/self-managed-agents) for the local-agent path.

## Agent discovery failed [#agent-discovery-failed]

Error name:

```txt
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)

`CopilotKitAgentDiscoveryError` comes from the v1 hooks, such as
`useCoAgentStateRender`, and from the v1 GraphQL runtime. With
`@copilotkit/react-core/v2`, `useAgent` throws an `Error` with this message for
the same cause:

```txt
useAgent: Agent '<id>' not found after runtime sync (runtimeUrl=<url>). ...
```

**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`):
  ```ts
  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](/mastra/backend/runtime-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 [#agent-route-returned-404]

Error strings:

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

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

```json
{ "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 errors in [Agent discovery failed](#agent-discovery-failed).

**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](/mastra/troubleshooting/common-issues#connect-route-returns-404-on-a-fresh-thread).

## Agent run failed [#agent-run-failed]

Error string:

```txt
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 [#capability-discovery-failed]

Error string:

```txt
Failed to fetch capabilities for agent "<name>"
```

**Where:** a `console.warn` in the runtime's server logs, from the `/info` handler.

**Cause:** the `getCapabilities()` call of the named agent threw. The `/info`
response still lists the agent, without capabilities.

**Fix:** read the error after the colon, and correct the `getCapabilities()`
method of the agent.
