Common Copilot Issues - Copilotkit

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

tsx

<CopilotKitProvider runtimeUrl="/api/copilotkit">
</CopilotKitProvider>

Or, if you're using CopilotCloud:

tsx

<CopilotKitProvider publicApiKey="<your-copilot-cloud-public-api-key>">
</CopilotKitProvider>

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

The LLM model string isn't a model the runtime's provider actually supports — double-check against 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 for the tool_handler_failed code.

Tools I registered don't show up

Open the 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.