Common Copilot Issues

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

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.

Info

Have an issue not listed here? Open a ticket on GitHub or reach out on Discord and we'll help. PRs adding your own troubleshooting notes are very welcome.

Network errors / API not found#

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

Check your endpoint configuration

Verify your runtimeUrl in CopilotKit:

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

Or, if you're using CopilotCloud:

<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

localhost vs 127.0.0.1

If you're running locally and getting connection errors, try 127.0.0.1 instead of localhost:

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

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.

"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.

Check your FastAPI / backend setup

Confirm the CopilotKit SDK is mounted. If you're using Python + FastAPI, follow the Remote Python Endpoint guide.

Test the /info endpoint directly

curl -v -d '{}' http://localhost:8000/copilotkit/info

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

{
  "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.

Tunnel creation hangs#

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

Router / ISP blocking tunnel connections

Verify connectivity:

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

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.

Common Copilot Issues

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

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.

Info

Have an issue not listed here? Open a ticket on GitHub or reach out on Discord and we'll help. PRs adding your own troubleshooting notes are very welcome.

Network errors / API not found#

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

Check your endpoint configuration

Verify your runtimeUrl in CopilotKit:

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

Or, if you're using CopilotCloud:

<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

localhost vs 127.0.0.1

If you're running locally and getting connection errors, try 127.0.0.1 instead of localhost:

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

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.

"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.

Check your FastAPI / backend setup

Confirm the CopilotKit SDK is mounted. If you're using Python + FastAPI, follow the Remote Python Endpoint guide.

Test the /info endpoint directly

curl -v -d '{}' http://localhost:8000/copilotkit/info

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

{
  "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.

Tunnel creation hangs#

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

Router / ISP blocking tunnel connections

Verify connectivity:

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

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.