---
title: Common Copilot Issues
description: Network errors, endpoint not found, tunnel timeouts, and other common issues when wiring up CopilotKit with the Built-in Agent.
icon: "lucide/LifeBuoy"
---

Welcome to the CopilotKit troubleshooting guide. This page covers the most common issues you'll hit while wiring up a Built-in Agent, plus the usual fixes.

<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

If you're getting network or API errors, here's how to troubleshoot.

<Accordions>
<Accordion title="Check your endpoint configuration">
Verify your `runtimeUrl` in `CopilotKit`:

```tsx
<CopilotKit runtimeUrl="/api/copilotkit">
  {/* Your app */}
</CopilotKit>
```

Or, if you're using CopilotCloud:

```tsx
<CopilotKit publicApiKey="<your-copilot-cloud-public-api-key>">
  {/* Your app */}
</CopilotKit>
```

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
- Using CopilotCloud but also setting `runtimeUrl` — omit `runtimeUrl` and keep only `publicApiKey`
</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
```

Usually caused by local DNS / `/etc/hosts` issues.
</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

If you're getting a *"CopilotKit's Remote Endpoint not found"* error, the `/info` endpoint isn't reachable from the runtime.

<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](/backend/copilot-runtime) 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" }
  ],
  "sdkVersion": "0.1.32"
}
```

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

## 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

Usually one of:

{/* TODO: retarget if model-selection is canonicalized at root */}
- The LLM model string isn't a model the runtime's provider actually supports — double-check against [Model Selection](/built-in-agent/model-selection).
- The Built-in Agent's `prompt` is empty and the user message is "do nothing" — 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

- Open the [Inspector](../inspector) → **Frontend Tools** panel. If the tool isn't there, the hook call didn't land — confirm the component is actually mounted.
- If the tool is listed but the agent never calls it, the model may not know when to use it. Tweak the `description` to include the trigger phrase.
- For v1 → v2 migrations, `useCopilotAction` split into `useFrontendTool` / `useComponent` / `useHumanInTheLoop` — make sure you're using the right one.
