@juspay/neurolink
Version:
The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002
1,303 lines (1,302 loc) • 49.2 kB
JavaScript
/**
* Robust Error Handling Utilities for NeuroLink
* Provides structured error management for tool execution and system operations
*/
import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
import { logger } from "./logger.js";
import { CircuitBreakerOpenError } from "../types/index.js";
import { HITLTimeoutError } from "../hitl/hitlErrors.js";
// Error codes for different scenarios
export const ERROR_CODES = {
// Tool errors
TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
TOOL_TIMEOUT: "TOOL_TIMEOUT",
TOOL_VALIDATION_FAILED: "TOOL_VALIDATION_FAILED",
// Parameter errors
INVALID_PARAMETERS: "INVALID_PARAMETERS",
MISSING_REQUIRED_PARAM: "MISSING_REQUIRED_PARAM",
// System errors
MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED",
NETWORK_ERROR: "NETWORK_ERROR",
PERMISSION_DENIED: "PERMISSION_DENIED",
PROXY_WORKER_LIFECYCLE_FAILED: "PROXY_WORKER_LIFECYCLE_FAILED",
// Provider errors
PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE",
PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED",
// Cancellation
OPERATION_ABORTED: "OPERATION_ABORTED",
// Configuration errors
INVALID_CONFIGURATION: "INVALID_CONFIGURATION",
MISSING_CONFIGURATION: "MISSING_CONFIGURATION",
// Video validation errors
INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION",
INVALID_VIDEO_LENGTH: "INVALID_VIDEO_LENGTH",
INVALID_VIDEO_ASPECT_RATIO: "INVALID_VIDEO_ASPECT_RATIO",
INVALID_VIDEO_AUDIO: "INVALID_VIDEO_AUDIO",
INVALID_VIDEO_MODE: "INVALID_VIDEO_MODE",
MISSING_VIDEO_IMAGE: "MISSING_VIDEO_IMAGE",
EMPTY_VIDEO_PROMPT: "EMPTY_VIDEO_PROMPT",
VIDEO_PROMPT_TOO_LONG: "VIDEO_PROMPT_TOO_LONG",
// Image validation errors
EMPTY_IMAGE_PATH: "EMPTY_IMAGE_PATH",
INVALID_IMAGE_TYPE: "INVALID_IMAGE_TYPE",
IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE",
IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL",
INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT",
INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE",
IMAGE_BUFFER_INVALID: "IMAGE_BUFFER_INVALID",
// Generic file/CSV processing errors
FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED",
CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
// PDF validation errors
PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED: "PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED",
PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED: "PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED",
PDF_PAGE_COUNT_UNVERIFIABLE: "PDF_PAGE_COUNT_UNVERIFIABLE",
PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED",
PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD",
// Rate limiter errors
RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL",
RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT",
RATE_LIMITER_RESET: "RATE_LIMITER_RESET",
// Evaluation errors
SCORER_NOT_FOUND: "SCORER_NOT_FOUND",
EVALUATION_VALIDATION_FAILED: "EVALUATION_VALIDATION_FAILED",
EVALUATION_TIMEOUT: "EVALUATION_TIMEOUT",
EVALUATION_EXECUTION_FAILED: "EVALUATION_EXECUTION_FAILED",
// PPT validation errors
MISSING_PPT_PROPERTIES: "MISSING_PPT_PROPERTIES",
INVALID_PPT_PAGES: "INVALID_PPT_PAGES",
INVALID_PPT_FORMAT: "INVALID_PPT_FORMAT",
INVALID_PPT_PROVIDER: "INVALID_PPT_PROVIDER",
INVALID_PPT_OUTPUT_OPTIONS: "INVALID_PPT_OUTPUT_OPTIONS",
INVALID_PPT_OUTPUT_PATH: "INVALID_PPT_OUTPUT_PATH",
INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH",
INVALID_PPT_MODE: "INVALID_PPT_MODE",
INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT",
// CSV validation/parsing errors (#1199)
CSV_INVALID_INPUT: "CSV_INVALID_INPUT",
CSV_ROW_INVALID: "CSV_ROW_INVALID",
CSV_FILE_ACCESS_FAILED: "CSV_FILE_ACCESS_FAILED",
CSV_PARSE_FAILED: "CSV_PARSE_FAILED",
};
/**
* Enhanced error class with structured information
*/
export class NeuroLinkError extends Error {
code;
category;
severity;
retriable;
retryAfterMs;
context;
timestamp;
toolName;
serverId;
constructor(options) {
super(options.message);
this.name = "NeuroLinkError";
this.code = options.code;
this.category = options.category;
this.severity = options.severity;
this.retriable = options.retriable;
this.retryAfterMs = options.retryAfterMs;
this.context = options.context || {};
this.timestamp = new Date();
this.toolName = options.toolName;
this.serverId = options.serverId;
// Preserve original error stack if provided
if (options.originalError) {
this.stack = options.originalError.stack;
this.context.originalMessage = options.originalError.message;
}
}
/**
* Convert to JSON for logging and serialization
*/
toJSON() {
return {
code: this.code,
message: this.message,
category: this.category,
severity: this.severity,
retriable: this.retriable,
context: this.context,
timestamp: this.timestamp,
toolName: this.toolName,
serverId: this.serverId,
};
}
}
/**
* Error factory for common error scenarios
*/
export class ErrorFactory {
/**
* Create a tool not found error
*/
static toolNotFound(toolName, availableTools) {
return new NeuroLinkError({
code: ERROR_CODES.TOOL_NOT_FOUND,
message: `Tool '${toolName}' not found`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { toolName, availableTools },
toolName,
});
}
/**
* Create a tool execution failed error
*/
static toolExecutionFailed(toolName, originalError, serverId) {
return new NeuroLinkError({
code: ERROR_CODES.TOOL_EXECUTION_FAILED,
message: `Tool '${toolName}' execution failed: ${originalError.message}`,
category: ErrorCategory.EXECUTION,
severity: ErrorSeverity.HIGH,
retriable: true,
originalError,
toolName,
serverId,
});
}
/**
* Create a tool timeout error.
*
* `timeoutMs` is the bound that was actually exceeded. Pass `budget` when
* the timeout happened inside a retry loop, so the error can say which
* number it is reporting: a reader who sees `timeoutMs: 120000` next to an
* `executionTime` of 483005 will otherwise conclude the timeout was never
* enforced, when in fact four attempts of 120s each were.
*
* `budget.exhausted` marks the case where the whole-execution ceiling ran
* out rather than a single attempt overrunning; that error is NOT retriable,
* because there is no budget left to retry into.
*/
static toolTimeout(toolName, timeoutMs, serverId, budget) {
const scope = budget?.exhausted
? `exhausted its ${budget.totalTimeoutMs}ms total budget`
: budget?.maxAttempts && budget.maxAttempts > 1
? `timed out after ${timeoutMs}ms on attempt ${budget.attempt ?? 1} of ${budget.maxAttempts}`
: `timed out after ${timeoutMs}ms`;
return new NeuroLinkError({
code: ERROR_CODES.TOOL_TIMEOUT,
message: `Tool '${toolName}' ${scope}`,
category: ErrorCategory.TIMEOUT,
severity: ErrorSeverity.HIGH,
// A single attempt timing out is worth another try; an exhausted total
// budget is not — retrying it can only overshoot the caller's ceiling.
retriable: budget?.exhausted !== true,
context: { timeoutMs, ...(budget ?? {}) },
toolName,
serverId,
});
}
/**
* Create a parameter validation error
*/
static invalidParameters(toolName, validationError, providedParams) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PARAMETERS,
message: `Invalid parameters for tool '${toolName}': ${validationError.message}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { providedParams },
originalError: validationError,
toolName,
});
}
/**
* Create a network error
*/
static networkError(toolName, originalError, serverId) {
return new NeuroLinkError({
code: ERROR_CODES.NETWORK_ERROR,
message: `Network error in tool '${toolName}': ${originalError.message}`,
category: ErrorCategory.NETWORK,
severity: ErrorSeverity.HIGH,
retriable: true,
originalError,
toolName,
serverId,
});
}
/**
* Create a memory exhaustion error
*/
static memoryExhausted(toolName, memoryUsageMB) {
return new NeuroLinkError({
code: ERROR_CODES.MEMORY_EXHAUSTED,
message: `Memory exhausted during tool '${toolName}' execution (${memoryUsageMB}MB used)`,
category: ErrorCategory.RESOURCE,
severity: ErrorSeverity.CRITICAL,
retriable: false,
context: { memoryUsageMB },
toolName,
});
}
/**
* Create a typed abort error preserving the originating exception. Callers
* can switch on `error.category === ErrorCategory.ABORT` and
* `error.code === ERROR_CODES.OPERATION_ABORTED` instead of message-string
* matching DOMException / AI SDK error wrappers.
*
* `error.name` is intentionally set to "AbortError" (overriding the default
* "NeuroLinkError") so existing callers that branch on
* `err.name === "AbortError"` keep working without code changes — the new
* structured fields (category, code, retriable) are additive.
*/
static aborted(originalError) {
const err = new NeuroLinkError({
code: ERROR_CODES.OPERATION_ABORTED,
message: originalError?.message || "The operation was aborted",
category: ErrorCategory.ABORT,
severity: ErrorSeverity.LOW,
retriable: false,
context: {},
originalError,
});
err.name = "AbortError";
return err;
}
// ============================================================================
// CONFIGURATION ERRORS
// ============================================================================
/**
* Create a missing configuration error (e.g., missing API key)
*/
static missingConfiguration(configName, context) {
return new NeuroLinkError({
code: ERROR_CODES.MISSING_CONFIGURATION,
message: `Missing required configuration: ${configName}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.HIGH,
retriable: false,
context: context || {},
});
}
/**
* Create an invalid configuration error (e.g., NaN for numeric values)
*/
static invalidConfiguration(configName, reason, context) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_CONFIGURATION,
message: `Invalid configuration for '${configName}': ${reason}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.HIGH,
retriable: false,
context: context || {},
});
}
// ============================================================================
// CSV VALIDATION/PARSING ERRORS (#1199)
// ============================================================================
/**
* Create an invalid CSV input error (e.g. an empty filePath/csvString argument).
*/
static csvInvalidInput(message) {
return new NeuroLinkError({
code: ERROR_CODES.CSV_INVALID_INPUT,
message,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {},
});
}
/**
* Create a CSV row-shape violation error (#384) — a parsed row that isn't a
* string-keyed object with string values.
*/
static csvRowInvalid(message, rowNumber) {
return new NeuroLinkError({
code: ERROR_CODES.CSV_ROW_INVALID,
message,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { rowNumber },
});
}
/**
* Create a CSV file access error (bad path, permissions, ENOENT/EACCES) (#375).
*/
static csvFileAccessFailed(message, filePath, originalError) {
return new NeuroLinkError({
code: ERROR_CODES.CSV_FILE_ACCESS_FAILED,
message,
category: ErrorCategory.RESOURCE,
severity: ErrorSeverity.HIGH,
retriable: false,
context: { filePath },
originalError,
});
}
/**
* Create a CSV read/parse failure error (#375) — source stream errors and
* csv-parser errors both route through this, carrying the enriched
* `buildCsvParseErrorMessage` context in `message`.
*/
static csvParseFailed(message, context, originalError) {
return new NeuroLinkError({
code: ERROR_CODES.CSV_PARSE_FAILED,
message,
category: ErrorCategory.EXECUTION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context,
originalError,
});
}
// ============================================================================
// VIDEO VALIDATION ERRORS
// ============================================================================
/**
* Create an invalid video resolution error
*/
static invalidVideoResolution(resolution) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_VIDEO_RESOLUTION,
message: `Invalid resolution '${resolution}'. Use '720p' or '1080p'`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.video.resolution",
providedValue: resolution,
suggestions: ["Use '720p' for standard HD", "Use '1080p' for full HD"],
},
});
}
/**
* Create an invalid video length error
*/
static invalidVideoLength(length) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_VIDEO_LENGTH,
message: `Invalid length '${length}'. Use 4, 6, or 8 seconds`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.video.length",
providedValue: length,
suggestions: [
"Use 4 for short clips",
"Use 6 for balanced duration (recommended)",
"Use 8 for longer videos",
],
},
});
}
/**
* Create an invalid video aspect ratio error
*/
static invalidVideoAspectRatio(aspectRatio) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_VIDEO_ASPECT_RATIO,
message: `Invalid aspect ratio '${aspectRatio}'. Use '9:16' or '16:9'`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.video.aspectRatio",
providedValue: aspectRatio,
suggestions: [
"Use '9:16' for portrait/vertical video",
"Use '16:9' for landscape",
],
},
});
}
/**
* Create an invalid video audio option error
*/
static invalidVideoAudio(audio) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_VIDEO_AUDIO,
message: `Invalid audio option '${audio}'. Must be true or false`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.video.audio",
providedValue: audio,
suggestions: [
"Set audio: true to enable audio generation",
"Set audio: false to disable",
],
},
});
}
/**
* Create an invalid video mode error
*/
static invalidVideoMode() {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_VIDEO_MODE,
message: "Video generation requires output.mode to be 'video'",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.mode",
suggestions: ["Set output: { mode: 'video' } for video generation"],
},
});
}
/**
* Create a missing video image error
*/
static missingVideoImage() {
return new NeuroLinkError({
code: ERROR_CODES.MISSING_VIDEO_IMAGE,
message: "Video generation requires an input image",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.images",
suggestions: [
"Provide an image via input.images array",
"Example: input: { text: 'prompt', images: [imageBuffer] }",
],
},
});
}
/**
* Create an empty video prompt error
*/
static emptyVideoPrompt() {
return new NeuroLinkError({
code: ERROR_CODES.EMPTY_VIDEO_PROMPT,
message: "Video prompt cannot be empty",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.text",
suggestions: [
"Provide a text prompt describing the desired video motion/content",
"Example: 'Smooth camera pan with dramatic lighting'",
],
},
});
}
/**
* Create a video prompt too long error
*/
static videoPromptTooLong(length, maxLength) {
return new NeuroLinkError({
code: ERROR_CODES.VIDEO_PROMPT_TOO_LONG,
message: `Video prompt must be ${maxLength} characters or less (got ${length})`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.text",
providedLength: length,
maxLength,
suggestions: [
`Shorten your prompt to ${maxLength} characters or less`,
"Focus on key visual elements and camera motion",
],
},
});
}
// ============================================================================
// IMAGE VALIDATION ERRORS
// ============================================================================
/**
* Create an empty image path error
*/
static emptyImagePath() {
return new NeuroLinkError({
code: ERROR_CODES.EMPTY_IMAGE_PATH,
message: "Image path or URL cannot be empty",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.images",
suggestions: ["Provide a valid file path or URL"],
},
});
}
/**
* Create an invalid image type error
*/
static invalidImageType() {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_IMAGE_TYPE,
message: "Image must be a Buffer, file path string, or URL",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.images",
suggestions: [
"Provide image as Buffer: fs.readFileSync('image.jpg')",
"Or as file path string: './image.jpg'",
"Or as URL: 'https://example.com/image.jpg'",
],
},
});
}
// ============================================================================
// PDF VALIDATION ERRORS
// ============================================================================
/**
* Create a PDF page limit exceeded error
*/
static pdfPageLimitExceeded(estimatedPages, maxPages, provider) {
const alternatives = [
`Split the PDF into smaller files (max ${maxPages} pages each)`,
"Extract only the pages you need using a PDF editor",
"For large files, consider Google AI Studio which supports up to 2000MB file size (though page limits still apply)",
"Convert specific pages to images manually before processing",
"Bypass this limit with { enforceLimits: false } (not recommended - may cause API errors or unexpected costs)",
];
return new NeuroLinkError({
code: ERROR_CODES.PDF_PAGE_LIMIT_EXCEEDED,
message: `PDF page limit exceeded: ${estimatedPages} pages detected, but ${provider} supports maximum ${maxPages} pages.\n\n` +
`Alternatives:\n` +
alternatives.map((alt, i) => `${i + 1}. ${alt}`).join("\n"),
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
estimatedPages,
maxPages,
provider,
alternatives,
},
});
}
/**
* The combined page count across every PDF in one request exceeds what the
* provider accepts (#309). Distinct from `pdfPageLimitExceeded`, which is
* per-file — here each document can be individually legal.
*/
static pdfAggregatePageLimitExceeded(fileCount, totalPages, maxPages, provider) {
return new NeuroLinkError({
code: ERROR_CODES.PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED,
message: `[PDF] Combined page count across ${fileCount} PDF(s) (${totalPages}) exceeds the ` +
`${maxPages}-page limit for ${provider}. ` +
`Split the request or reduce the number of PDFs.`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { fileCount, totalPages, maxPages, provider },
});
}
/**
* The combined byte size across every PDF in one request exceeds what the
* provider accepts (#309).
*/
static pdfAggregateSizeLimitExceeded(fileCount, totalMB, maxSizeMB, provider) {
return new NeuroLinkError({
code: ERROR_CODES.PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED,
message: `[PDF] Combined size across ${fileCount} PDF(s) (${totalMB.toFixed(2)}MB) exceeds the ` +
`${maxSizeMB}MB limit for ${provider}.`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { fileCount, totalMB, maxSizeMB, provider },
});
}
/**
* A PDF supplied through the untrusted `input.content` surface could not be
* parsed for a page count (#309). Caller-supplied `metadata.pages` is not
* authoritative there, so an unreadable document is rejected rather than
* admitted with an assumed count of zero.
*/
static pdfPageCountUnverifiable(filenames, provider) {
return new NeuroLinkError({
code: ERROR_CODES.PDF_PAGE_COUNT_UNVERIFIABLE,
message: `[PDF] Cannot verify the page count for ${filenames.length} PDF(s) supplied via ` +
`input.content (${filenames.join(", ")}). Provide readable PDFs, or submit them ` +
`via input.pdfFiles where page counts are derived during detection.`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { filenames, provider },
});
}
/**
* The PDF is encrypted and no password was supplied (#258).
*/
static pdfPasswordRequired() {
return new NeuroLinkError({
code: ERROR_CODES.PDF_PASSWORD_REQUIRED,
message: "This PDF is password-protected. Supply the password via " +
"`pdfOptions: { password: '…' }` (SDK) or `--pdf-password` (CLI).",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
});
}
/**
* A password was supplied for an encrypted PDF but it was incorrect (#258).
*/
static pdfIncorrectPassword() {
return new NeuroLinkError({
code: ERROR_CODES.PDF_INCORRECT_PASSWORD,
message: "The password supplied for this PDF is incorrect. Check the " +
"`pdfOptions.password` / `--pdf-password` value and try again.",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
});
}
/**
* Create an image too large error
*/
static imageTooLarge(sizeMB, maxMB) {
return new NeuroLinkError({
code: ERROR_CODES.IMAGE_TOO_LARGE,
message: `Image size (${sizeMB}MB) exceeds maximum (${maxMB}MB)`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.images",
sizeMB,
maxMB,
suggestions: [
`Compress or resize the image to under ${maxMB}MB`,
"Use a lower quality JPEG compression",
"Reduce image dimensions",
],
},
});
}
/**
* Create an invalid image size error (NaN/Infinity/negative byte length).
* Distinct from `imageTooLarge` — this rejects a malformed size value
* before it reaches the max-size comparison, since `NaN > maxSize` and
* `-1 > maxSize` both evaluate to `false` and would otherwise let a
* corrupted stat/header value silently skip the guard.
*/
static invalidImageSize(size) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_IMAGE_SIZE,
message: `Invalid image size: ${size} (must be a finite, non-negative number)`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.images",
size,
},
});
}
/**
* Create an image too small error
*/
static imageTooSmall() {
return new NeuroLinkError({
code: ERROR_CODES.IMAGE_TOO_SMALL,
message: "Image data is too small to be a valid image file",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.images",
suggestions: ["Provide a valid JPEG, PNG, or WebP image file"],
},
});
}
/**
* Create an invalid image format error
*/
static invalidImageFormat() {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_IMAGE_FORMAT,
message: "Unsupported image format. Use JPEG, PNG, or WebP",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.images",
suggestions: [
"Convert your image to JPEG, PNG, or WebP format",
"Ensure the file is not corrupted",
"Check that the file extension matches the actual format",
],
},
});
}
/**
* Create an image buffer validation error: empty, undersized, or a
* truncated buffer detected by `ImageProcessor.validateBufferNotEmpty()`.
* Takes the fully-formed message so call sites keep their specific
* byte-count detail instead of a fixed generic message.
*/
static imageBufferInvalid(message) {
return new NeuroLinkError({
code: ERROR_CODES.IMAGE_BUFFER_INVALID,
message,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { field: "input.images" },
});
}
// ============================================================================
// RATE LIMITER ERRORS
// ============================================================================
/**
* Create a rate limiter queue full error
*/
static rateLimiterQueueFull(maxQueueSize) {
return new NeuroLinkError({
code: ERROR_CODES.RATE_LIMITER_QUEUE_FULL,
message: `Rate limiter queue full: too many pending requests (${maxQueueSize} max)`,
category: ErrorCategory.RESOURCE,
severity: ErrorSeverity.HIGH,
retriable: true,
context: { maxQueueSize },
});
}
/**
* Create a rate limiter queue timeout error
*/
static rateLimiterQueueTimeout(timeoutMs) {
return new NeuroLinkError({
code: ERROR_CODES.RATE_LIMITER_QUEUE_TIMEOUT,
message: `Rate limiter queue timeout: request exceeded ${timeoutMs}ms wait time`,
category: ErrorCategory.TIMEOUT,
severity: ErrorSeverity.HIGH,
retriable: true,
context: { timeoutMs },
});
}
/**
* Create a rate limiter reset error
*/
static rateLimiterReset() {
return new NeuroLinkError({
code: ERROR_CODES.RATE_LIMITER_RESET,
message: "Rate limiter was reset while request was pending",
category: ErrorCategory.EXECUTION,
severity: ErrorSeverity.MEDIUM,
retriable: true,
context: {},
});
}
// ============================================================================
// PPT VALIDATION ERRORS
// ============================================================================
/**
* Create a generic missing PPT property error
*/
static missingPPTProperty(field, suggestions) {
const defaultSuggestions = [`Provide the required '${field}' field`];
return new NeuroLinkError({
code: ERROR_CODES.MISSING_PPT_PROPERTIES,
message: `PPT generation requires '${field}' field`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field,
suggestions: suggestions || defaultSuggestions,
},
});
}
/**
* Create an invalid PPT pages error
*/
static invalidPPTPages(pages, reason) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_PAGES,
message: `Invalid pages value '${pages}': ${reason}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.ppt.pages",
providedValue: pages,
suggestions: [
"Use a number between 5 and 50",
"For longer presentations, consider breaking into multiple decks",
],
},
});
}
/**
* Create an invalid PPT format error
*/
static invalidPPTFormat(format) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_FORMAT,
message: `Invalid format '${format}'. Only 'pptx' is supported`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.ppt.format",
providedValue: format,
suggestions: ["Use format: 'pptx' or omit (defaults to 'pptx')"],
},
});
}
/**
* Create a generic invalid PPT output options error
*/
static invalidPPTOutputOptions(field, value, validOptions) {
const suggestions = validOptions
? validOptions.map((opt) => `Use '${opt}'`)
: ["Check the documentation for valid options"];
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_OUTPUT_OPTIONS,
message: `Invalid ${field} value '${value}'`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: `output.ppt.${field}`,
providedValue: value,
suggestions,
},
});
}
/**
* Create an invalid PPT output path error
*/
static invalidPPTOutputPath(path, reason) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_OUTPUT_PATH,
message: `Invalid outputPath '${path}': ${reason}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.ppt.outputPath",
providedValue: path,
suggestions: [
"Provide a valid file path string",
"Example: './presentations/my-deck.pptx'",
"Omit to use auto-generated path",
],
},
});
}
/**
* Create an invalid PPT mode error
*/
static invalidPPTMode() {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_MODE,
message: "Presentation generation requires output.mode to be 'ppt'",
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.mode",
suggestions: [
"Set output: { mode: 'ppt' } for presentation generation",
],
},
});
}
/**
* Create an invalid PPT prompt error
*/
static invalidPPTPrompt(reason) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_PROMPT,
message: `Invalid PPT prompt: ${reason}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "input.text",
suggestions: [
"Provide a non-empty text prompt",
"Keep the prompt under 1000 characters",
"Focus on key topics and structure for the presentation",
],
},
});
}
/**
* Create an invalid PPT logo path error
*/
static invalidPPTLogoPath(path, reason) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_LOGO_PATH,
message: `Invalid logoPath '${path}': ${reason}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "output.ppt.logoPath",
providedValue: path,
suggestions: [
"Provide a valid file path string",
"Example: './assets/logo.png'",
"Omit to skip logo inclusion",
],
},
});
}
/**
* Create an invalid PPT provider error
*/
static invalidPPTProvider(provider) {
return new NeuroLinkError({
code: ERROR_CODES.INVALID_PPT_PROVIDER,
message: `Invalid provider '${provider}' for PPT generation. Supported providers: vertex, openai, azure, anthropic, google-ai, bedrock`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: {
field: "provider",
providedValue: provider,
suggestions: [
"Use 'vertex' for Google Vertex AI (Gemini)",
"Use 'openai' for OpenAI GPT models",
"Use 'azure' for Azure OpenAI",
"Use 'anthropic' for Anthropic Claude models",
"Use 'google-ai' for Google AI Studio (Gemini)",
"Use 'bedrock' for AWS Bedrock (Claude, Llama, Nova, etc.)",
],
},
});
}
// ============================================================================
// EVALUATION ERRORS
// ============================================================================
/**
* Create a scorer not found error
*/
static scorerNotFound(scorerId, availableScorers) {
return new NeuroLinkError({
code: ERROR_CODES.SCORER_NOT_FOUND,
message: `Scorer '${scorerId}' not found. Use neurolink.getAvailableScorers() to see available scorers.`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { scorerId, availableScorers },
});
}
/**
* Create an evaluation validation error
*/
static evaluationValidationFailed(scorerId, errors) {
return new NeuroLinkError({
code: ERROR_CODES.EVALUATION_VALIDATION_FAILED,
message: `Invalid input for scorer '${scorerId}': ${errors.join(", ")}`,
category: ErrorCategory.VALIDATION,
severity: ErrorSeverity.MEDIUM,
retriable: false,
context: { scorerId, validationErrors: errors },
});
}
/**
* Create an evaluation timeout error
*/
static evaluationTimeout(operation, timeoutMs) {
return new NeuroLinkError({
code: ERROR_CODES.EVALUATION_TIMEOUT,
message: `Evaluation ${operation} timed out after ${timeoutMs}ms`,
category: ErrorCategory.TIMEOUT,
severity: ErrorSeverity.HIGH,
retriable: true,
context: { operation, timeoutMs },
});
}
/**
* Create an evaluation execution failed error
*/
static evaluationExecutionFailed(operation, originalError) {
return new NeuroLinkError({
code: ERROR_CODES.EVALUATION_EXECUTION_FAILED,
message: `Evaluation ${operation} failed: ${originalError.message}`,
category: ErrorCategory.EXECUTION,
severity: ErrorSeverity.HIGH,
retriable: false,
originalError,
});
}
// ============================================================================
// PROXY ROLLING-WORKER ERRORS
// ============================================================================
/**
* Create a proxy rolling-worker lifecycle error. Preserves the caller's exact
* message so existing substring-based assertions keep working, while giving
* callers a typed `code`/`category` to branch on instead of string-matching
* generic `Error` instances.
*/
static proxyWorkerLifecycle(message, context) {
return new NeuroLinkError({
code: ERROR_CODES.PROXY_WORKER_LIFECYCLE_FAILED,
message,
category: ErrorCategory.SYSTEM,
severity: ErrorSeverity.HIGH,
retriable: false,
context: context || {},
});
}
// ============================================================================
// GENERIC FILE / CSV PROCESSING ERRORS
// ============================================================================
/**
* Create a generic file-processing-failed error (e.g. an unrecognized or
* corrupt file in `processUnifiedFilesArray`). Preserves the original error
* as `originalError` (stack + message copied onto the new error's context).
*/
static fileProcessingFailed(filename, originalError) {
return new NeuroLinkError({
code: ERROR_CODES.FILE_PROCESSING_FAILED,
message: `Failed to process file "${filename}": ${originalError.message}`,
category: ErrorCategory.EXECUTION,
severity: ErrorSeverity.HIGH,
retriable: false,
context: { filename },
originalError,
});
}
/**
* Create a generic CSV-processing-failed error (explicit `csvFiles` path,
* distinct from `fileProcessingFailed` so callers can classify CSV-specific
* failures separately). Preserves the original error as `originalError`.
*/
static csvProcessingFailed(filename, originalError) {
return new NeuroLinkError({
code: ERROR_CODES.CSV_PROCESSING_FAILED,
message: `Failed to process CSV file "${filename}": ${originalError.message}`,
category: ErrorCategory.EXECUTION,
severity: ErrorSeverity.HIGH,
retriable: false,
context: { filename },
originalError,
});
}
}
/**
* Timeout wrapper for async operations
*/
export async function withTimeout(promise, timeoutMs, timeoutError) {
let timer;
const timeoutPromise = new Promise((_, reject) => {
timer = setTimeout(() => {
reject(timeoutError || new Error(`Operation timed out after ${timeoutMs}ms`));
}, timeoutMs);
});
try {
return await Promise.race([promise, timeoutPromise]);
}
finally {
clearTimeout(timer);
}
}
/**
* Retry mechanism for retriable operations
*/
export async function withRetry(operation, options) {
const { maxAttempts, delayMs, isRetriable = () => true, onRetry } = options;
let lastError;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return await operation();
}
catch (error) {
lastError = error instanceof Error ? error : new Error(String(error));
// Don't retry on the last attempt or if error is not retriable
if (attempt === maxAttempts || !isRetriable(lastError)) {
throw lastError;
}
if (onRetry) {
onRetry(attempt, lastError);
}
// Wait before retry
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
}
if (lastError) {
throw lastError;
}
throw new Error("Retry operation failed with no error information");
}
/**
* Circuit breaker for preventing cascading failures
*/
export class CircuitBreaker {
failureThreshold;
resetTimeoutMs;
failures = 0;
lastFailureTime = 0;
state = "closed";
name;
constructor(failureThreshold = 5, resetTimeoutMs = 60000, name = "tool-execution") {
this.failureThreshold = failureThreshold;
this.resetTimeoutMs = resetTimeoutMs;
this.name = name;
}
async execute(operation) {
if (this.state === "open") {
const retryAfterMs = this.resetTimeoutMs - (Date.now() - this.lastFailureTime);
if (retryAfterMs > 0) {
throw new CircuitBreakerOpenError({
breakerName: this.name,
retryAfter: new Date(this.lastFailureTime + this.resetTimeoutMs),
retryAfterMs,
breakerState: "open",
failureCount: this.failures,
});
}
this.state = "half-open";
}
try {
const result = await operation();
this.onSuccess();
return result;
}
catch (error) {
this.onFailure();
throw error;
}
}
onSuccess() {
this.failures = 0;
this.state = "closed";
}
onFailure() {
this.failures++;
this.lastFailureTime = Date.now();
if (this.failures >= this.failureThreshold) {
this.state = "open";
}
}
getState() {
return this.state;
}
getFailureCount() {
return this.failures;
}
}
/**
* Detect AbortError from any source (DOMException, plain Error, or message-based).
* Used to short-circuit retry/fallback loops when an abort signal fires.
*
* Uses `includes()` for message checks because provider error handlers
* (e.g., googleVertex.formatProviderError) wrap the original AbortError
* in a formatted error like "❌ Provider Error\n\nThis operation was aborted\n\n..."
* which destroys the exact message match.
*/
export function isAbortError(error) {
if (error instanceof DOMException && error.name === "AbortError") {
return true;
}
if (error instanceof Error && error.name === "AbortError") {
return true;
}
// Typed NeuroLinkError abort - canonical from-now-on shape.
if (error instanceof NeuroLinkError &&
error.category === ErrorCategory.ABORT) {
return true;
}
if (error instanceof Error &&
(error.message?.includes("This operation was aborted") ||
error.message?.includes("The operation was aborted") ||
error.message?.includes("The user aborted a request") ||
// Anthropic SDK's APIUserAbortError — name is plain "Error", so only
// the message identifies it. Missing this classified real aborts as
// provider failures (ERROR log + fallback consulted on a user cancel).
error.message?.includes("Request was aborted"))) {
return true;
}
return false;
}
/**
* Error handler that decides whether to retry based on error type
*/
export function isRetriableError(error) {
if (error instanceof NeuroLinkError) {
return error.retriable;
}
if (error instanceof HITLTimeoutError) {
return false;
}
// Check for common retriable error patterns
const retriablePatterns = [
/timeout/i,
/network/i,
/connection/i,
/temporary/i,
/rate limit/i,
/quota/i,
/503/i, // Service unavailable
/502/i, // Bad gateway
/504/i, // Gateway timeout
];
return retriablePatterns.some((pattern) => pattern.test(error.message));
}
/**
* Determines if an error is likely recoverable (rate limit, timeout, network issues).
* Useful for deciding whether to retry or fail fast.
*/
export function isRecoverableError(error) {
// Check NeuroLinkError.retriable first
const errorWithRetriable = error;
if ("retriable" in error &&
typeof errorWithRetriable.retriable === "boolean") {
return errorWithRetriable.retriable;
}
const message = error.message?.toLowerCase() || "";
// Rate limit errors
if (message.includes("rate limit") || message.includes("too many requests")) {
return true;
}
if (/\b429\b/.test(message)) {
return true;
}
// Timeout errors
if (message.includes("timeout") ||
message.includes("etimedout") ||
message.includes("timed out")) {
return true;
}
// Network errors
if (message.includes("econnreset") ||
message.includes("econnrefused") ||
message.includes("network") ||
message.includes("socket")) {
return true;
}
// Server errors (use word boundaries to avoid false matches)
if (/\b50[0234]\b/.test(message)) {
return true;
}
return false;
}
/**
* Enhanced error logger that provides structured logging
*/
export function logStructuredError(error, context) {
const logData = {
...error.toJSON(),
...context,
};
switch (error.severity) {
case ErrorSeverity.CRITICAL:
logger.error(`[CRITICAL] ${error.message}`, logData);
break;
case ErrorSeverity.HIGH:
logger.error(`[HIGH] ${error.message}`, logData);
break;
case ErrorSeverity.MEDIUM:
logger.warn(`[MEDIUM] ${error.message}`, logData);
break;
case ErrorSeverity.LOW:
logger.info(`[LOW] ${error.message}`, logData);
break;
}
}