@copilotkit/shared
Version:
<img src="https://github.com/user-attachments/assets/0a6b64d9-e193-4940-a3f6-60334ac34084" alt="banner" style="border-radius: 12px; border: 2px solid #d6d4fa;" />
439 lines (435 loc) • 18.3 kB
JavaScript
const require_runtime = require('../_virtual/_rolldown/runtime.cjs');
const require_index = require('../index.cjs');
let graphql = require("graphql");
//#region src/utils/errors.ts
let Severity = /* @__PURE__ */ function(Severity) {
Severity["CRITICAL"] = "critical";
Severity["WARNING"] = "warning";
Severity["INFO"] = "info";
return Severity;
}({});
let ErrorVisibility = /* @__PURE__ */ function(ErrorVisibility) {
ErrorVisibility["BANNER"] = "banner";
ErrorVisibility["TOAST"] = "toast";
ErrorVisibility["SILENT"] = "silent";
ErrorVisibility["DEV_ONLY"] = "dev_only";
return ErrorVisibility;
}({});
const ERROR_NAMES = {
COPILOT_ERROR: "CopilotError",
COPILOT_API_DISCOVERY_ERROR: "CopilotApiDiscoveryError",
COPILOT_REMOTE_ENDPOINT_DISCOVERY_ERROR: "CopilotKitRemoteEndpointDiscoveryError",
COPILOT_KIT_AGENT_DISCOVERY_ERROR: "CopilotKitAgentDiscoveryError",
COPILOT_KIT_LOW_LEVEL_ERROR: "CopilotKitLowLevelError",
COPILOT_KIT_VERSION_MISMATCH_ERROR: "CopilotKitVersionMismatchError",
RESOLVED_COPILOT_KIT_ERROR: "ResolvedCopilotKitError",
CONFIGURATION_ERROR: "ConfigurationError",
MISSING_PUBLIC_API_KEY_ERROR: "MissingPublicApiKeyError",
UPGRADE_REQUIRED_ERROR: "UpgradeRequiredError"
};
const BANNER_ERROR_NAMES = [
ERROR_NAMES.CONFIGURATION_ERROR,
ERROR_NAMES.MISSING_PUBLIC_API_KEY_ERROR,
ERROR_NAMES.UPGRADE_REQUIRED_ERROR,
ERROR_NAMES.COPILOT_API_DISCOVERY_ERROR,
ERROR_NAMES.COPILOT_REMOTE_ENDPOINT_DISCOVERY_ERROR,
ERROR_NAMES.COPILOT_KIT_AGENT_DISCOVERY_ERROR
];
const COPILOT_CLOUD_ERROR_NAMES = BANNER_ERROR_NAMES;
let CopilotKitErrorCode = /* @__PURE__ */ function(CopilotKitErrorCode) {
CopilotKitErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
CopilotKitErrorCode["NOT_FOUND"] = "NOT_FOUND";
CopilotKitErrorCode["AGENT_NOT_FOUND"] = "AGENT_NOT_FOUND";
CopilotKitErrorCode["API_NOT_FOUND"] = "API_NOT_FOUND";
CopilotKitErrorCode["REMOTE_ENDPOINT_NOT_FOUND"] = "REMOTE_ENDPOINT_NOT_FOUND";
CopilotKitErrorCode["AUTHENTICATION_ERROR"] = "AUTHENTICATION_ERROR";
CopilotKitErrorCode["MISUSE"] = "MISUSE";
CopilotKitErrorCode["UNKNOWN"] = "UNKNOWN";
CopilotKitErrorCode["VERSION_MISMATCH"] = "VERSION_MISMATCH";
CopilotKitErrorCode["CONFIGURATION_ERROR"] = "CONFIGURATION_ERROR";
CopilotKitErrorCode["MISSING_PUBLIC_API_KEY_ERROR"] = "MISSING_PUBLIC_API_KEY_ERROR";
CopilotKitErrorCode["UPGRADE_REQUIRED_ERROR"] = "UPGRADE_REQUIRED_ERROR";
return CopilotKitErrorCode;
}({});
const BASE_URL = "https://docs.copilotkit.ai";
const getSeeMoreMarkdown = (link) => `See more: [${link}](${link})`;
const ERROR_CONFIG = {
[CopilotKitErrorCode.NETWORK_ERROR]: {
statusCode: 503,
troubleshootingUrl: `${BASE_URL}/troubleshooting/common-issues#network-errors-api-not-found`,
visibility: ErrorVisibility.BANNER,
severity: Severity.CRITICAL
},
[CopilotKitErrorCode.NOT_FOUND]: {
statusCode: 404,
troubleshootingUrl: `${BASE_URL}/troubleshooting/common-issues#network-errors-api-not-found`,
visibility: ErrorVisibility.BANNER,
severity: Severity.CRITICAL
},
[CopilotKitErrorCode.AGENT_NOT_FOUND]: {
statusCode: 500,
troubleshootingUrl: `${BASE_URL}/langgraph-python/coagent-troubleshooting/common-coagent-issues#i-am-getting-agent-not-found-error`,
visibility: ErrorVisibility.BANNER,
severity: Severity.CRITICAL
},
[CopilotKitErrorCode.API_NOT_FOUND]: {
statusCode: 404,
troubleshootingUrl: `${BASE_URL}/troubleshooting/common-issues#network-errors-api-not-found`,
visibility: ErrorVisibility.BANNER,
severity: Severity.CRITICAL
},
[CopilotKitErrorCode.REMOTE_ENDPOINT_NOT_FOUND]: {
statusCode: 404,
troubleshootingUrl: `${BASE_URL}/troubleshooting/common-issues#remote-endpoint-not-found-error`,
visibility: ErrorVisibility.BANNER,
severity: Severity.CRITICAL
},
[CopilotKitErrorCode.AUTHENTICATION_ERROR]: {
statusCode: 401,
troubleshootingUrl: `${BASE_URL}/troubleshooting/common-issues`,
visibility: ErrorVisibility.BANNER,
severity: Severity.CRITICAL
},
[CopilotKitErrorCode.MISUSE]: {
statusCode: 400,
troubleshootingUrl: null,
visibility: ErrorVisibility.DEV_ONLY,
severity: Severity.WARNING
},
[CopilotKitErrorCode.UNKNOWN]: {
statusCode: 500,
visibility: ErrorVisibility.TOAST,
severity: Severity.CRITICAL
},
[CopilotKitErrorCode.CONFIGURATION_ERROR]: {
statusCode: 400,
troubleshootingUrl: null,
severity: Severity.WARNING,
visibility: ErrorVisibility.BANNER
},
[CopilotKitErrorCode.MISSING_PUBLIC_API_KEY_ERROR]: {
statusCode: 400,
troubleshootingUrl: null,
severity: Severity.CRITICAL,
visibility: ErrorVisibility.BANNER
},
[CopilotKitErrorCode.UPGRADE_REQUIRED_ERROR]: {
statusCode: 402,
troubleshootingUrl: null,
severity: Severity.WARNING,
visibility: ErrorVisibility.BANNER
},
[CopilotKitErrorCode.VERSION_MISMATCH]: {
statusCode: 400,
troubleshootingUrl: null,
visibility: ErrorVisibility.DEV_ONLY,
severity: Severity.INFO
}
};
var CopilotKitError = class extends graphql.GraphQLError {
constructor({ message = "Unknown error occurred", code, severity, visibility }) {
const name = ERROR_NAMES.COPILOT_ERROR;
const config = ERROR_CONFIG[code];
const { statusCode } = config;
const resolvedVisibility = visibility ?? config.visibility ?? ErrorVisibility.TOAST;
const resolvedSeverity = severity ?? ("severity" in config ? config.severity : void 0);
super(message, { extensions: {
name,
statusCode,
code,
visibility: resolvedVisibility,
severity: resolvedSeverity,
troubleshootingUrl: "troubleshootingUrl" in config ? config.troubleshootingUrl : null,
originalError: {
message,
stack: (/* @__PURE__ */ new Error()).stack
}
} });
this.code = code;
this.name = name;
this.statusCode = statusCode;
this.severity = resolvedSeverity;
this.visibility = resolvedVisibility;
}
};
/**
* Error thrown when we can identify wrong usage of our components.
* This helps us notify the developer before real errors can happen
*
* @extends CopilotKitError
*/
var CopilotKitMisuseError = class extends CopilotKitError {
constructor({ message, code = CopilotKitErrorCode.MISUSE }) {
const docsLink = "troubleshootingUrl" in ERROR_CONFIG[code] && ERROR_CONFIG[code].troubleshootingUrl ? getSeeMoreMarkdown(ERROR_CONFIG[code].troubleshootingUrl) : null;
const finalMessage = docsLink ? `${message}.\n\n${docsLink}` : message;
super({
message: finalMessage,
code
});
this.name = ERROR_NAMES.COPILOT_API_DISCOVERY_ERROR;
}
};
const getVersionMismatchErrorMessage = ({ reactCoreVersion, runtimeVersion, runtimeClientGqlVersion }) => `Version mismatch detected: @copilotkit/runtime@${runtimeVersion ?? ""} is not compatible with @copilotkit/react-core@${reactCoreVersion} and @copilotkit/runtime-client-gql@${runtimeClientGqlVersion}. Please ensure all installed copilotkit packages are on the same version.`;
/**
* Error thrown when CPK versions does not match
*
* @extends CopilotKitError
*/
var CopilotKitVersionMismatchError = class extends CopilotKitError {
constructor({ reactCoreVersion, runtimeVersion, runtimeClientGqlVersion }) {
const code = CopilotKitErrorCode.VERSION_MISMATCH;
super({
message: getVersionMismatchErrorMessage({
reactCoreVersion,
runtimeVersion,
runtimeClientGqlVersion
}),
code
});
this.name = ERROR_NAMES.COPILOT_KIT_VERSION_MISMATCH_ERROR;
}
};
/**
* Error thrown when the CopilotKit API endpoint cannot be discovered or accessed.
* This typically occurs when:
* - The API endpoint URL is invalid or misconfigured
* - The API service is not running at the expected location
* - There are network/firewall issues preventing access
*
* @extends CopilotKitError
*/
var CopilotKitApiDiscoveryError = class extends CopilotKitError {
constructor(params = {}) {
const url = params.url ?? "";
let operationSuffix = "";
if (url?.includes("/info")) operationSuffix = `when fetching CopilotKit info`;
else if (url.includes("/actions/execute")) operationSuffix = `when attempting to execute actions.`;
else if (url.includes("/agents/state")) operationSuffix = `when attempting to get agent state.`;
else if (url.includes("/agents/execute")) operationSuffix = `when attempting to execute agent(s).`;
const message = params.message ?? (params.url ? `Failed to find CopilotKit API endpoint at url ${params.url} ${operationSuffix}` : `Failed to find CopilotKit API endpoint.`);
const code = params.code ?? CopilotKitErrorCode.API_NOT_FOUND;
const errorMessage = `${message}.\n\n${getSeeMoreMarkdown(ERROR_CONFIG[code].troubleshootingUrl)}`;
super({
message: errorMessage,
code
});
this.name = ERROR_NAMES.COPILOT_API_DISCOVERY_ERROR;
}
};
/**
* This error is used for endpoints specified in runtime's remote endpoints. If they cannot be contacted
* This typically occurs when:
* - The API endpoint URL is invalid or misconfigured
* - The API service is not running at the expected location
*
* @extends CopilotKitApiDiscoveryError
*/
var CopilotKitRemoteEndpointDiscoveryError = class extends CopilotKitApiDiscoveryError {
constructor(params) {
const message = params?.message ?? (params?.url ? `Failed to find or contact remote endpoint at url ${params.url}` : "Failed to find or contact remote endpoint");
const code = CopilotKitErrorCode.REMOTE_ENDPOINT_NOT_FOUND;
super({
message,
code
});
this.name = ERROR_NAMES.COPILOT_REMOTE_ENDPOINT_DISCOVERY_ERROR;
}
};
/**
* Error thrown when a LangGraph agent cannot be found or accessed.
* This typically occurs when:
* - The specified agent name does not exist in the deployment
* - The agent configuration is invalid or missing
* - The agent service is not properly deployed or initialized
*
* @extends CopilotKitError
*/
var CopilotKitAgentDiscoveryError = class extends CopilotKitError {
constructor(params) {
const { agentName, availableAgents } = params;
const code = CopilotKitErrorCode.AGENT_NOT_FOUND;
const seeMore = getSeeMoreMarkdown(ERROR_CONFIG[code].troubleshootingUrl);
let message;
if (availableAgents.length) {
const agentList = availableAgents.map((agent) => agent.name).join(", ");
if (agentName) message = `Agent '${agentName}' was not found. Available agents are: ${agentList}. Please verify the agent name in your configuration and ensure it matches one of the available agents.\n\n${seeMore}`;
else message = `The requested agent was not found. Available agents are: ${agentList}. Please verify the agent name in your configuration and ensure it matches one of the available agents.\n\n${seeMore}`;
} else message = `${agentName ? `Agent '${agentName}'` : "The requested agent"} was not found. Please set up at least one agent before proceeding. ${seeMore}`;
super({
message,
code
});
this.name = ERROR_NAMES.COPILOT_KIT_AGENT_DISCOVERY_ERROR;
}
};
/**
* Handles low-level networking errors that occur before a request reaches the server.
* These errors arise from issues in the underlying communication infrastructure rather than
* application-level logic or server responses. Typically used to handle "fetch failed" errors
* where no HTTP status code is available.
*
* Common scenarios include:
* - Connection failures (ECONNREFUSED) when server is down/unreachable
* - DNS resolution failures (ENOTFOUND) when domain can't be resolved
* - Timeouts (ETIMEDOUT) when request takes too long
* - Protocol/transport layer errors like SSL/TLS issues
*/
var CopilotKitLowLevelError = class extends CopilotKitError {
constructor({ error, url, message }) {
let code = CopilotKitErrorCode.NETWORK_ERROR;
const errorCode = error.code;
const errorMessage = message ?? resolveLowLevelErrorMessage({
errorCode,
url
});
super({
message: errorMessage,
code
});
this.name = ERROR_NAMES.COPILOT_KIT_LOW_LEVEL_ERROR;
}
};
/**
* Generic catch-all error handler for HTTP responses from the CopilotKit API where a status code is available.
* Used when we receive an HTTP error status and wish to handle broad range of them
*
* This differs from CopilotKitLowLevelError in that:
* - ResolvedCopilotKitError: Server was reached and returned an HTTP status
* - CopilotKitLowLevelError: Error occurred before reaching server (e.g. network failure)
*
* @param status - The HTTP status code received from the API response
* @param message - Optional error message to include
* @param code - Optional specific CopilotKitErrorCode to override default behavior
*
* Default behavior:
* - 400 Bad Request: Maps to CopilotKitApiDiscoveryError
* - All other status codes: Maps to UNKNOWN error code if no specific code provided
*/
var ResolvedCopilotKitError = class extends CopilotKitError {
constructor({ status, message, code, isRemoteEndpoint, url }) {
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;
}
};
var ConfigurationError = class extends CopilotKitError {
constructor(message) {
super({
message,
code: CopilotKitErrorCode.CONFIGURATION_ERROR
});
this.name = ERROR_NAMES.CONFIGURATION_ERROR;
this.severity = Severity.WARNING;
}
};
var MissingPublicApiKeyError = class extends ConfigurationError {
constructor(message) {
super(message);
this.name = ERROR_NAMES.MISSING_PUBLIC_API_KEY_ERROR;
this.severity = Severity.CRITICAL;
}
};
var UpgradeRequiredError = class extends ConfigurationError {
constructor(message) {
super(message);
this.name = ERROR_NAMES.UPGRADE_REQUIRED_ERROR;
this.severity = Severity.WARNING;
}
};
/**
* Checks if an error is already a structured CopilotKit error.
* This utility centralizes the logic for detecting structured errors across the codebase.
*
* @param error - The error to check
* @returns true if the error is already structured, false otherwise
*/
function isStructuredCopilotKitError(error) {
return error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError || error?.name && error.name.includes("CopilotKit") || error?.extensions?.code !== void 0;
}
/**
* Returns the error as-is if it's already structured, otherwise converts it using the provided converter function.
* This utility centralizes the pattern of preserving structured errors while converting unstructured ones.
*
* @param error - The error to process
* @param converter - Function to convert unstructured errors to structured ones
* @returns The structured error
*/
function ensureStructuredError(error, converter) {
return isStructuredCopilotKitError(error) ? error : converter(error);
}
async function getPossibleVersionMismatch({ runtimeVersion, runtimeClientGqlVersion }) {
if (!runtimeVersion || runtimeVersion === "" || !runtimeClientGqlVersion) return;
if (require_index.COPILOTKIT_VERSION !== runtimeVersion || require_index.COPILOTKIT_VERSION !== runtimeClientGqlVersion || runtimeVersion !== runtimeClientGqlVersion) return {
runtimeVersion,
runtimeClientGqlVersion,
reactCoreVersion: require_index.COPILOTKIT_VERSION,
message: getVersionMismatchErrorMessage({
runtimeVersion,
runtimeClientGqlVersion,
reactCoreVersion: require_index.COPILOTKIT_VERSION
})
};
}
const resolveLowLevelErrorMessage = ({ errorCode, url }) => {
const troubleshootingLink = ERROR_CONFIG[CopilotKitErrorCode.NETWORK_ERROR].troubleshootingUrl;
const genericMessage = (description = `Failed to fetch from url ${url}.`) => `${description}.
Possible reasons:
- -The server may have an error preventing it from returning a response (Check the server logs for more info).
- -The server might be down or unreachable
- -There might be a network issue (e.g., DNS failure, connection timeout)
- -The URL might be incorrect
- -The server is not running on the specified port
${getSeeMoreMarkdown(troubleshootingLink)}`;
if (url.includes("/info")) return genericMessage(`Failed to fetch CopilotKit agents/action information from url ${url}.`);
if (url.includes("/actions/execute")) return genericMessage(`Fetch call to ${url} to execute actions failed.`);
if (url.includes("/agents/state")) return genericMessage(`Fetch call to ${url} to get agent state failed.`);
if (url.includes("/agents/execute")) return genericMessage(`Fetch call to ${url} to execute agent(s) failed.`);
switch (errorCode) {
case "ECONNREFUSED": return `Connection to ${url} was refused. Ensure the server is running and accessible.\n\n${getSeeMoreMarkdown(troubleshootingLink)}`;
case "ENOTFOUND": return `The server on ${url} could not be found. Check the URL or your network configuration.\n\n${getSeeMoreMarkdown(ERROR_CONFIG[CopilotKitErrorCode.NOT_FOUND].troubleshootingUrl)}`;
case "ETIMEDOUT": return `The connection to ${url} timed out. The server might be overloaded or taking too long to respond.\n\n${getSeeMoreMarkdown(troubleshootingLink)}`;
default: return;
}
};
//#endregion
exports.BANNER_ERROR_NAMES = BANNER_ERROR_NAMES;
exports.COPILOT_CLOUD_ERROR_NAMES = COPILOT_CLOUD_ERROR_NAMES;
exports.ConfigurationError = ConfigurationError;
exports.CopilotKitAgentDiscoveryError = CopilotKitAgentDiscoveryError;
exports.CopilotKitApiDiscoveryError = CopilotKitApiDiscoveryError;
exports.CopilotKitError = CopilotKitError;
exports.CopilotKitErrorCode = CopilotKitErrorCode;
exports.CopilotKitLowLevelError = CopilotKitLowLevelError;
exports.CopilotKitMisuseError = CopilotKitMisuseError;
exports.CopilotKitRemoteEndpointDiscoveryError = CopilotKitRemoteEndpointDiscoveryError;
exports.CopilotKitVersionMismatchError = CopilotKitVersionMismatchError;
exports.ERROR_CONFIG = ERROR_CONFIG;
exports.ERROR_NAMES = ERROR_NAMES;
exports.ErrorVisibility = ErrorVisibility;
exports.MissingPublicApiKeyError = MissingPublicApiKeyError;
exports.ResolvedCopilotKitError = ResolvedCopilotKitError;
exports.Severity = Severity;
exports.UpgradeRequiredError = UpgradeRequiredError;
exports.ensureStructuredError = ensureStructuredError;
exports.getPossibleVersionMismatch = getPossibleVersionMismatch;
exports.isStructuredCopilotKitError = isStructuredCopilotKitError;
//# sourceMappingURL=errors.cjs.map