CopilotKit
Reference / core / enums

CopilotKitCoreErrorCode

Stable error codes surfaced through the onError subscriber callback.

Overview

CopilotKitCoreErrorCode enumerates the stable, machine-readable codes that CopilotKitCore attaches to errors. You encounter it in the onError callback of a subscriber, where you can branch on code to handle specific failures.

Import

import { CopilotKitCoreErrorCode } from "@copilotkit/core";

Definition

enum CopilotKitCoreErrorCode {
  RUNTIME_INFO_FETCH_FAILED = "runtime_info_fetch_failed",
  AGENT_CONNECT_FAILED = "agent_connect_failed",
  AGENT_RUN_FAILED = "agent_run_failed",
  AGENT_RUN_FAILED_EVENT = "agent_run_failed_event",
  AGENT_RUN_ERROR_EVENT = "agent_run_error_event",
  TOOL_ARGUMENT_PARSE_FAILED = "tool_argument_parse_failed",
  TOOL_HANDLER_FAILED = "tool_handler_failed",
  TOOL_NOT_FOUND = "tool_not_found",
  AGENT_NOT_FOUND = "agent_not_found",
  AGENT_THREAD_LOCKED = "agent_thread_locked",
  TRANSCRIPTION_FAILED = "transcription_failed",
  TRANSCRIPTION_SERVICE_NOT_CONFIGURED = "transcription_service_not_configured",
  TRANSCRIPTION_INVALID_AUDIO = "transcription_invalid_audio",
  TRANSCRIPTION_RATE_LIMITED = "transcription_rate_limited",
  TRANSCRIPTION_AUTH_FAILED = "transcription_auth_failed",
  TRANSCRIPTION_NETWORK_ERROR = "transcription_network_error",
  SUBSCRIBER_CALLBACK_FAILED = "subscriber_callback_failed",
}

Members

RUNTIME_INFO_FETCH_FAILEDruntime_info_fetch_failed

Fetching runtime info (agents, version, capabilities) from the runtime URL failed.

AGENT_CONNECT_FAILEDagent_connect_failed

Connecting an agent to the runtime failed.

AGENT_RUN_FAILEDagent_run_failed

An agent run threw before or while starting.

AGENT_RUN_FAILED_EVENTagent_run_failed_event

The agent emitted a RUN_FAILED event during execution.

AGENT_RUN_ERROR_EVENTagent_run_error_event

The agent emitted a RUN_ERROR event during execution.

TOOL_ARGUMENT_PARSE_FAILEDtool_argument_parse_failed

A tool call's arguments could not be parsed against the tool's schema.

TOOL_HANDLER_FAILEDtool_handler_failed

A frontend tool handler threw while executing.

TOOL_NOT_FOUNDtool_not_found

The agent called a tool that is not registered.

AGENT_NOT_FOUNDagent_not_found

An operation referenced an agent ID that is not registered.

AGENT_THREAD_LOCKEDagent_thread_locked

An agent run failed because the thread is already locked by another active run.

TRANSCRIPTION_FAILEDtranscription_failed

Audio transcription failed for an unspecified reason.

TRANSCRIPTION_SERVICE_NOT_CONFIGUREDtranscription_service_not_configured

Transcription was requested but no transcription service is configured.

TRANSCRIPTION_INVALID_AUDIOtranscription_invalid_audio

The supplied audio could not be transcribed because it was invalid.

TRANSCRIPTION_RATE_LIMITEDtranscription_rate_limited

The transcription service rejected the request due to rate limiting.

TRANSCRIPTION_AUTH_FAILEDtranscription_auth_failed

Authentication with the transcription service failed.

TRANSCRIPTION_NETWORK_ERRORtranscription_network_error

A network error occurred while contacting the transcription service.

SUBSCRIBER_CALLBACK_FAILEDsubscriber_callback_failed

A subscriber callback threw while handling an event.

Usage

copilotkit.subscribe({
  onError: ({ code, error, context }) => {
    if (code === CopilotKitCoreErrorCode.AGENT_THREAD_LOCKED) {
      // Show "Agent is busy, retry?" UI
      return;
    }
    console.error(code, error, context);
  },
});

Related