Skip to content

common-issues.mdx

Latest commit

 

History

History
133 lines (98 loc) · 4.36 KB

common-issues.mdx

File metadata and controls

133 lines (98 loc) · 4.36 KB
Raw
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.

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.

Network errors / API not found

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

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

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.

Confirm the CopilotKit SDK is mounted. If you're using Python + FastAPI, follow the [Remote Python Endpoint](/backend/copilot-runtime) guide. ```bash 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.

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:

{/* 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.
  • 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.