CopilotKit/CopilotKit · error · CopilotKitApiDiscoveryError

${message}

Error message

${message}

What it means

This is the constructor dispatch of a CopilotKit HTTP error (in utils/errors.ts): given a fetch status, it chooses the right error class — 400 becomes CopilotKitApiDiscoveryError, 404 on a remote endpoint becomes CopilotKitRemoteEndpointDiscoveryError — propagating the caller-supplied message. The throw you see is the 400/404 discovery failure path, meaning the runtime URL/agent endpoint probing failed.

Source

Thrown at packages/shared/src/utils/errors.ts:409

export class ResolvedCopilotKitError extends CopilotKitError {
  constructor({
    status,
    message,
    code,
    isRemoteEndpoint,
    url,
  }: {
    status: number;
    message?: string;
    code?: CopilotKitErrorCode;
    isRemoteEndpoint?: boolean;
    url?: string;
  }) {
    let resolvedCode = code;
    if (!resolvedCode) {
      switch (status) {
        case 400:
          throw new CopilotKitApiDiscoveryError({ message, url });
        case 404:
          throw isRemoteEndpoint
            ? new CopilotKitRemoteEndpointDiscoveryError({ message, url })
            : new CopilotKitApiDiscoveryError({ message, url });
        default:
          resolvedCode = CopilotKitErrorCode.UNKNOWN;
          break;
      }
    }

    super({ message, code: resolvedCode });
    this.name = ERROR_NAMES.RESOLVED_COPILOT_KIT_ERROR;
  }
}

export class ConfigurationError extends CopilotKitError {
  constructor(message: string) {
    super({ message, code: CopilotKitErrorCode.CONFIGURATION_ERROR });

View on GitHub (pinned to 68fbe97d87)

Solutions

1. Verify the runtimeUrl points at the CopilotKit runtime endpoint and that it responds (curl the /info or agents route)
2. Fix proxy/rewrite rules so discovery paths reach the runtime
3. If 404 from a remote endpoint, confirm the remote agent is registered and the URL includes any required base path

Example fix

// before
const runtimeUrl = "https://myapp.com"; // frontend, not runtime
// after
const runtimeUrl = "https://myapp.com/api/copilotkit";

const res = await fetch(`${runtimeUrl}/info`);
if (!res.ok) console.warn(`Runtime probe failed: ${res.status}`);

try { /* init/discovery */ } catch (e) {
  if (e instanceof CopilotKitApiDiscoveryError || e instanceof CopilotKitRemoteEndpointDiscoveryError) {
    // check runtimeUrl, proxy config
  }
  throw e;
}

When it happens

Trigger: Probing a CopilotKit runtime that returns 400 (malformed discovery request / wrong URL path) or 404 (no runtime at that URL), during client initialization or agent discovery.

Common situations: Wrong runtimeUrl (pointing at the frontend origin or a nonexistent route), runtime not deployed, reverse proxy stripping paths, agent route not registered on the runtime.

Related errors

• intelligence file ${handle} -> ${response.status}
• intelligence file upload -> ${response.status}
• download failed (HTTP ${res.status})
• read channel message failed (HTTP ${res.status}): ${(await r
• ProxiedCopilotRuntimeAgent requires a runtimeUrl when transp

AI-assisted analysis of CopilotKit/CopilotKit@68fbe97d87 (2026-08-27). Data as JSON: /api/errors/9077b3b431771669. Report an issue: GitHub.