# Common Copilot Issues

> Network errors, endpoint not found, tunnel timeouts, and other common issues when wiring up CopilotKit with the Built-in Agent.

<Callout type="info">
Have an issue not listed here? Open a ticket on [GitHub](https://github.com/CopilotKit/CopilotKit/issues) or reach out on [Discord](https://discord.com/invite/6dffbvGU3D) and we'll help. PRs adding your own troubleshooting notes are very welcome.
</Callout>

## Network errors / API not found [#network-errors--api-not-found]

<Accordions>
<Accordion title="Check your endpoint configuration">
Verify the configured `runtimeUrl`.

Common issues:

- Missing leading slash in the endpoint path
- Wrong path relative to your app's base URL (or, if absolute, wrong full URL)
- Typos in the endpoint path
</Accordion>

<Accordion title="localhost vs 127.0.0.1">
If you're running locally and getting connection errors, try `127.0.0.1` instead of `localhost`:

```bash
# If this doesn't work:
http://localhost:3000/api/copilotkit

# Try this instead:
http://127.0.0.1:3000/api/copilotkit
```

The cause is usually a local DNS or `/etc/hosts` problem.
</Accordion>

<Accordion title="Verify your backend is running">
Make sure your backend:

- Is actually running on the port you expect
- Is reachable from your frontend
- Isn't blocked by CORS or a firewall

Revisit the [quickstart](../quickstart) if you want to double-check your setup.
</Accordion>
</Accordions>

## "Remote Endpoint not found" error [#remote-endpoint-not-found-error]

If you see `Failed to find or contact remote endpoint at url ...` (error code `REMOTE_ENDPOINT_NOT_FOUND`), the runtime cannot reach the `/info` endpoint.

<Accordions>
<Accordion title="Check your FastAPI / backend setup">
Confirm the CopilotKit SDK is mounted. If you're using Python + FastAPI, follow the [Remote Python Endpoint](/reference/v1/sdk/python/RemoteEndpoints) guide.
</Accordion>

<Accordion title="Test the /info endpoint directly">
```bash
curl -v -d '{}' http://localhost:8000/copilotkit/info
```

You should see a `200 OK` and a JSON body like:

```json
{
  "actions": [],
  "agents": [
    { "name": "my_agent", "description": "A helpful agent.", "type": "langgraph_agui" }
  ],
  "sdkVersion": "0.1.32"
}
```

If you see a different response, check your server logs.
</Accordion>
</Accordions>

## Tunnel creation hangs [#tunnel-creation-hangs]

If the tunnel creation process spins indefinitely, your router or ISP might be blocking the tunnel service.

<Accordions>
<Accordion title="Router / ISP blocking tunnel connections">
Verify connectivity:

```bash
ping tunnels.devcopilotkit.com
curl -I https://tunnels.devcopilotkit.com
telnet tunnels.devcopilotkit.com 443
```

If any of these fail:

- Check your router security settings
- Contact your ISP to see if they're blocking the connection
- Try a different network to confirm
</Accordion>
</Accordions>

## The Built-in Agent responds with an empty message [#the-built-in-agent-responds-with-an-empty-message]

The cause is usually one of these:

- The LLM model string isn't supported by the runtime's provider. Check it against [Model Selection](/model-selection).
- The Built-in Agent's `prompt` is empty and the user message gives it nothing useful to do. Give the agent a system prompt.
- A frontend tool is throwing during its handler and the agent is treating the empty result as the turn output. See [Error Debugging](./error-debugging) for the `tool_handler_failed` code.

## Tools I registered don't show up [#tools-i-registered-dont-show-up]

## Connect route returns 404 on a fresh thread [#connect-route-returns-404-on-a-fresh-thread]

If you self-host the runtime and see a `404` from `POST /agent/:agentId/connect`
right after the page loads, before any message is sent, it's almost always one
of two things:

<Accordions>
<Accordion title="The agentId isn't registered (most common)">
The runtime returns a `404` with this body when no agent matches the id in the URL:

```json
{ "error": "Agent not found", "message": "Agent 'default' does not exist" }
```

The prebuilt components connect to the agent named `"default"` unless you pass an
explicit `agentId`. Register one under that key:

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

Confirm the agent shows up by hitting [`GET {runtimeUrl}/info`](/vue/google-adk/backend/runtime-endpoints)
directly. See also the [error reference](./error-reference#agent-route-returned-404).
</Accordion>

<Accordion title="connect() runs before run() on a new thread">
The frontend mints a thread id and may call `connect()` to re-attach **before**
the first `run()` has produced any events. If a persistence backend learns about
a thread only when a run starts, the first connect can return 404 or another error.

The built-in [`InMemoryAgentRunner`](/vue/google-adk/backend/agent-runner) handles the common
cases, but a custom runner backed by an external memory layer must handle the
"unknown thread" path explicitly. Return an empty `RUN_STARTED`,
`MESSAGES_SNAPSHOT`, `RUN_FINISHED` sequence instead of failing. The
[AWS AgentCore integration](/vue/google-adk/deploy/agentcore) shows the exact pattern.
</Accordion>
</Accordions>

## Runtime memory keeps growing or the process runs out of heap [#runtime-memory-keeps-growing-or-the-process-runs-out-of-heap]

A long-lived server on the default `InMemoryAgentRunner` accumulates thread
history in process memory.

<Accordions>
<Accordion title="Tune or lower the in-memory bounds">
The store is bounded by default (1000 threads, 100 runs per thread, ~512 MiB of
retained history), but those defaults assume a reasonably sized heap. If your
process runs with a small `--max-old-space-size`, or your threads carry unusually
large payloads, lower the limits:

```ts
new InMemoryAgentRunner({ maxThreads: 200, maxBytes: 64 * 1024 ** 2 });
```

See [bounding in-memory history](/vue/google-adk/backend/agent-runner#bounding-in-memory-history)
for what each bound covers and what it deliberately does not.
</Accordion>

<Accordion title="You saw an eviction warning in the logs">
`InMemoryAgentRunner evicted in-memory thread history...` means the bounds are
doing their job. The process is safe, but that thread's scrollback is gone and
will not come back. If losing history matters, move to a durable runner:
[Self-host CopilotKit Intelligence](/vue/google-adk/intelligence/self-hosting), or your own
[custom runner](/vue/google-adk/backend/agent-runner#extending-a-runner-for-a-custom-backend)
backed by your datastore.
</Accordion>
</Accordions>
