Common Copilot Issues

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

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

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

Tunnel creation hangs

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

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.
  • 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 for the tool_handler_failed code.

Tools I registered don't show up

  • Open the Inspector and look for the Frontend Tools tab. If the tab is missing or does not list your tool, the hook call did not run. Make sure that the component is 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 LangGraph agents, also add an explicit instruction in system_prompt, especially for mandatory data-fetch tools where the agent must call the tool before answering.
  • For v1 to v2 migrations, useCopilotAction split into useFrontendTool, useComponent, and useHumanInTheLoop. Make sure you're using the right one.

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:

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.

How is this guide?