Common Copilot Issues
Network errors, endpoint not found, tunnel timeouts, and other common issues when wiring up CopilotKit with the Built-in Agent.
Network errors / API not found
Verify the configured runtimeUrl.
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
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/copilotkitThe cause is usually a local DNS or /etc/hosts problem.
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 see Failed to find or contact remote endpoint at url ... (error code REMOTE_ENDPOINT_NOT_FOUND), the runtime cannot reach the /info endpoint.
Confirm the CopilotKit SDK is mounted. If you're using Python + FastAPI, follow the Remote Python Endpoint guide.
curl -v -d '{}' http://localhost:8000/copilotkit/infoYou should see a 200 OK and a JSON body like:
{
"actions": [],
"agents": [
{ "name": "my_agent", "description": "A helpful agent.", "type": "langgraph_agui" }
],
"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 443If 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
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
promptis 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_failedcode.
Tools I registered don't show up
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:
The runtime returns a 404 with this body when no agent matches the id in the URL:
{ "error": "Agent not found", "message": "Agent 'default' does not exist" }The prebuilt components connect to the agent named "default" unless you pass an
explicit agentId. Register one under that key:
new CopilotRuntime({ agents: { default: myAgent } });Confirm the agent shows up by hitting GET {runtimeUrl}/info
directly. See also the error reference.
The frontend mints a thread id and may call connect() to re-attach before
the first run() has produced any events. If a persistence backend learns about
a thread only when a run starts, the first connect can return 404 or another error.
The built-in InMemoryAgentRunner handles the common
cases, but a custom runner backed by an external memory layer must handle the
"unknown thread" path explicitly. Return an empty RUN_STARTED,
MESSAGES_SNAPSHOT, RUN_FINISHED sequence instead of failing. The
AWS AgentCore integration shows the exact pattern.
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.
The store is bounded by default (1000 threads, 100 runs per thread, ~512 MiB of
retained history), but those defaults assume a reasonably sized heap. If your
process runs with a small --max-old-space-size, or your threads carry unusually
large payloads, lower the limits:
new InMemoryAgentRunner({ maxThreads: 200, maxBytes: 64 * 1024 ** 2 });See bounding in-memory history for what each bound covers and what it deliberately does not.
InMemoryAgentRunner evicted in-memory thread history... means the bounds are
doing their job. The process is safe, but that thread's scrollback is gone and
will not come back. If losing history matters, move to a durable runner:
Self-host CopilotKit Intelligence, or your own
custom runner
backed by your datastore.
How is this guide?