oneringaiv2
Documentation/Errors
v2.0.0-beta.1Snapshot bebdcd1Markdown ↗

Errors

Errors

Error types and handling

AgentPackageCompatibilityError class

📍 src/portable/AgentPackage.ts:58

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

AIError class

📍 src/domain/errors/AIErrors.ts:5

Custom error classes for the AI library

Constructor

constructor

typescript
constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode?: number,
    public readonly originalError?: Error
  )

Parameters:

  • message: string
  • code: string
  • statusCode: number | undefined (optional)
  • originalError: Error | undefined (optional)

ConnectorNotFoundError class

📍 src/domain/errors/AIErrors.ts:25

A connector could not be resolved in the current registry scope. Scoped registries use the same error for missing and hidden connectors so callers cannot distinguish their existence. Other lookup failures must retain their original type. Hosts decide whether absence permits a fallback; no HTTP status is assigned. Diagnostic messages must only list visible connectors.

Constructor

constructor

typescript
constructor(message = 'Connector not found in current scope.', originalError?: Error)

Parameters:

  • message: string (optional) (default: 'Connector not found in current scope.')
  • originalError: Error | undefined (optional)

ContextOverflowError class

📍 src/domain/errors/AIErrors.ts:426

Error thrown when context cannot be reduced to fit within limits after all graceful degradation levels have been exhausted.

Constructor

constructor

typescript
constructor(
    message: string,
    /** Detailed budget information for debugging */
    public readonly budget: ContextOverflowBudget
  )

Parameters:

  • message: string
  • budget: ContextOverflowBudget
Methods

getDegradationSummary()

Get a formatted summary of what was tried

typescript
getDegradationSummary(): string

Returns: string

getTopConsumers()

Get the top token consumers

typescript
getTopConsumers(count = 5): Array<{ component: string; tokens: number }>

Parameters:

  • count: number (optional) (default: 5)

Returns: { component: string; tokens: number; }[]

DependencyCycleError class

📍 src/domain/errors/AIErrors.ts:272

Error thrown when a dependency cycle is detected in a plan

Constructor

constructor

typescript
constructor(
    /** Task IDs forming the cycle (e.g., ['A', 'B', 'C', 'A']) */
    public readonly cycle: string[],
    /** Plan ID where the cycle was detected */
    public readonly planId?: string
  )

Parameters:

  • cycle: string[]
  • planId: string | undefined (optional)

ErrorHandler class

📍 src/core/ErrorHandler.ts:122

Centralized error handling for all agent types.

Features:

  • Consistent error logging with context
  • Automatic retry with exponential backoff
  • Error classification (recoverable vs fatal)
  • Metrics collection
  • Event emission for monitoring

Example:

typescript
const errorHandler = new ErrorHandler({
  maxRetries: 3,
  logErrors: true,
});

// Handle an error
errorHandler.handle(error, {
  agentType: 'agent',
  operation: 'run',
});

// Execute with retry
const result = await errorHandler.executeWithRetry(
  () => riskyOperation(),
  { agentType: 'agent', operation: 'riskyOperation' }
);
Constructor

constructor

typescript
constructor(config: ErrorHandlerConfig = {})

Parameters:

  • config: ErrorHandlerConfig (optional) (default: {})
Methods

handle()

Handle an error with context. Logs the error, emits events, and records metrics.

typescript
handle(error: Error, context: ErrorContext): void

Parameters:

  • error: Error
  • context: ErrorContext

Returns: void

executeWithRetry()

Execute a function with automatic retry on retryable errors.

typescript
async executeWithRetry<T>(
    fn: () => Promise<T>,
    context: ErrorContext
  ): Promise<T>

Parameters:

  • fn: () => Promise<T>
  • context: ErrorContext

Returns: Promise<T>

wrap()

Wrap a function with error handling (no retry). Useful for wrapping methods that already have their own retry logic.

typescript
wrap<TArgs extends unknown[], TResult>(
    fn: (...args: TArgs) => Promise<TResult>,
    contextFactory: (...args: TArgs) => ErrorContext
  ): (...args: TArgs) => Promise<TResult>

Parameters:

  • fn: (...args: TArgs) => Promise<TResult>
  • contextFactory: (...args: TArgs) => ErrorContext

Returns: (...args: TArgs) => Promise<TResult>

isRecoverable()

Check if an error is recoverable (can be retried or handled gracefully).

typescript
isRecoverable(error: Error): boolean

Parameters:

  • error: Error

Returns: boolean

isRetryable()

Check if an error should be retried.

typescript
isRetryable(error: Error): boolean

Parameters:

  • error: Error

Returns: boolean

addRetryablePattern()

Add a retryable pattern.

typescript
addRetryablePattern(pattern: string): void

Parameters:

  • pattern: string

Returns: void

removeRetryablePattern()

Remove a retryable pattern.

typescript
removeRetryablePattern(pattern: string): void

Parameters:

  • pattern: string

Returns: void

getConfig()

Get current configuration (read-only).

typescript
getConfig(): Readonly<Required<ErrorHandlerConfig>>

Returns: Readonly<Required<ErrorHandlerConfig>>

EvidenceError class

📍 src/core/evidence/validation.ts:5

Messages contain no source payloads, credentials, or backend exception text.

Constructor

constructor

typescript
constructor(readonly code: 'invalid' | 'capacity' | 'corrupt' | 'busy' | 'storage')

Parameters:

  • code: "invalid" | "capacity" | "corrupt" | "busy" | "storage"

FactSupersededError class

📍 src/memory/MemorySystem.ts:245

F1 — thrown by restoreFact when the target fact was superseded by a later non-archived fact. Un-archiving the predecessor without first handling the successor would leave two "current" values for the same predicate, breaking ranking and the singleValued invariant. Callers handle this by (a) archiving the successor first, or (b) using memory_forget on the successor.

Constructor

constructor

typescript
constructor(factId: FactId, supersededBy: FactId)

Parameters:

  • factId: string
  • supersededBy: string
Properties
Property Type Description
factId factId: string -
supersededBy supersededBy: string -

HelperOutputError class

📍 src/core/model-execution/ModelExecutor.ts:58

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

InvalidConfigError class

📍 src/domain/errors/AIErrors.ts:224

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

JsonParseError class

📍 src/utils/jsonRepair.ts:124

Error thrown by {@link parseJsonPermissive} when every strategy fails. Carries the first 500 chars of the raw input for debugging.

Constructor

constructor

typescript
constructor(message: string, rawText: string)

Parameters:

  • message: string
  • rawText: string
Properties
Property Type Description
rawSnippet rawSnippet: string First 500 chars of the raw text that failed to parse.

MCPConnectionError class

📍 src/domain/errors/MCPError.ts:27

Connection-related errors (failed to connect, disconnected unexpectedly)

Constructor

constructor

typescript
constructor(message: string, serverName?: string, cause?: Error)

Parameters:

  • message: string
  • serverName: string | undefined (optional)
  • cause: Error | undefined (optional)

MCPError class

📍 src/domain/errors/MCPError.ts:10

MCP Error Classes

Error hierarchy for MCP-related failures.

Constructor

constructor

typescript
constructor(
    message: string,
    public readonly serverName?: string,
    public readonly cause?: Error
  )

Parameters:

  • message: string
  • serverName: string | undefined (optional)
  • cause: Error | undefined (optional)

MCPProtocolError class

📍 src/domain/errors/MCPError.ts:52

Protocol-level errors (invalid message, unsupported capability)

Constructor

constructor

typescript
constructor(message: string, serverName?: string, cause?: Error)

Parameters:

  • message: string
  • serverName: string | undefined (optional)
  • cause: Error | undefined (optional)

MCPResourceError class

📍 src/domain/errors/MCPError.ts:77

Resource-related errors (resource not found, subscription failed)

Constructor

constructor

typescript
constructor(
    message: string,
    public readonly resourceUri: string,
    serverName?: string,
    cause?: Error
  )

Parameters:

  • message: string
  • resourceUri: string
  • serverName: string | undefined (optional)
  • cause: Error | undefined (optional)

MCPTimeoutError class

📍 src/domain/errors/MCPError.ts:37

Timeout errors (request timeout, connection timeout)

Constructor

constructor

typescript
constructor(
    message: string,
    public readonly timeoutMs: number,
    serverName?: string,
    cause?: Error
  )

Parameters:

  • message: string
  • timeoutMs: number
  • serverName: string | undefined (optional)
  • cause: Error | undefined (optional)

MongoOptimisticConcurrencyError class

📍 src/memory/adapters/mongo/MongoMemoryAdapter.ts:70

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

OptimisticConcurrencyError class

📍 src/memory/adapters/inmemory/InMemoryAdapter.ts:707

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

OwnerRequiredError class

📍 src/memory/AccessControl.ts:153

Thrown when a record would be created without an ownerId AND the calling scope carries no userId either. Every record must have an owner — either set explicitly by the caller (admin delegation) or inherited from scope.userId.

Constructor

constructor

typescript
constructor(public readonly recordKind: 'entity' | 'fact')

Parameters:

  • recordKind: "entity" | "fact"

PermissionDeniedError class

📍 src/memory/AccessControl.ts:134

Thrown by MemorySystem when a caller attempts a mutation against a record whose effective permissions deny write access. Reads that are denied return empty results rather than throwing (storage filters them out).

Constructor

constructor

typescript
constructor(
    public readonly recordId: string,
    public readonly recordKind: 'entity' | 'fact',
    public readonly operation: Permission,
  )

Parameters:

  • recordId: string
  • recordKind: "entity" | "fact"
  • operation: Permission

ProfileGeneratorMissingError class

📍 src/memory/MemorySystem.ts:204

Constructor

constructor

typescript
constructor()

ProviderAmbiguousOperationError class

📍 src/domain/errors/AIErrors.ts:206

A paid/external submission may have succeeded even though no handle was received.

Constructor

constructor

typescript
constructor(
    public readonly providerName: string,
    public readonly operation: string,
    public readonly recoveryMetadata?: Record<string, unknown>,
    originalError?: Error,
  )

Parameters:

  • providerName: string
  • operation: string
  • recoveryMetadata: Record<string, unknown> | undefined (optional)
  • originalError: Error | undefined (optional)

ProviderAuthError class

📍 src/domain/errors/AIErrors.ts:45

Constructor

constructor

typescript
constructor(providerName: string, message: string = 'Authentication failed')

Parameters:

  • providerName: string
  • message: string (optional) (default: 'Authentication failed')

ProviderCapabilityNotSupportedError class

📍 src/domain/errors/AIErrors.ts:189

Constructor

constructor

typescript
constructor(
    public readonly providerName: string,
    public readonly model: string,
    public readonly capability: string,
  )

Parameters:

  • providerName: string
  • model: string
  • capability: string

ProviderContextLengthError class

📍 src/domain/errors/AIErrors.ts:95

Constructor

constructor

typescript
constructor(
    providerName: string,
    public readonly maxTokens: number,
    public readonly requestedTokens?: number
  )

Parameters:

  • providerName: string
  • maxTokens: number
  • requestedTokens: number | undefined (optional)

ProviderError class

📍 src/domain/errors/AIErrors.ts:249

Constructor

constructor

typescript
constructor(
    public readonly providerName: string,
    message: string,
    statusCode?: number,
    originalError?: Error
  )

Parameters:

  • providerName: string
  • message: string
  • statusCode: number | undefined (optional)
  • originalError: Error | undefined (optional)

ProviderErrorMapper class

📍 src/infrastructure/providers/base/ProviderErrorMapper.ts:25

Maps provider-specific errors to our unified error types

Static Methods

static mapError()

Map any provider error to our standard error types

typescript
static mapError(error: any, context: ProviderErrorContext): AIError

Parameters:

  • error: any
  • context: ProviderErrorContext

Returns: AIError

static extractErrorDetails()

Extract rich error details for logging. Captures status, code, type, cause, headers, and stack from SDK errors.

typescript
static extractErrorDetails(error: any): Record<string, unknown>

Parameters:

  • error: any

Returns: Record<string, unknown>

ProviderMisalignmentError class

📍 src/domain/errors/AIErrors.ts:58

OpenAI safety monitor stopped a request for a potential misalignment policy violation.

Constructor

constructor

typescript
constructor(
    public readonly providerName: string,
    message: string,
    public readonly requestId?: string,
    public readonly responseId?: string,
    public readonly details?: unknown,
    originalError?: Error,
  )

Parameters:

  • providerName: string
  • message: string
  • requestId: string | undefined (optional)
  • responseId: string | undefined (optional)
  • details: unknown (optional)
  • originalError: Error | undefined (optional)
Properties
Property Type Description
providerCode providerCode: "misalignment_policy_violation" -

ProviderNotFoundError class

📍 src/domain/errors/AIErrors.ts:33

Constructor

constructor

typescript
constructor(providerName: string)

Parameters:

  • providerName: string

ProviderRateLimitError class

📍 src/domain/errors/AIErrors.ts:80

Constructor

constructor

typescript
constructor(
    providerName: string,
    public readonly retryAfter?: number
  )

Parameters:

  • providerName: string
  • retryAfter: number | undefined (optional)

ScopeInvariantError class

📍 src/memory/MemorySystem.ts:197

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

ScopeViolationError class

📍 src/memory/adapters/inmemory/InMemoryAdapter.ts:714

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

SemanticSearchUnavailableError class

📍 src/memory/MemorySystem.ts:211

Constructor

constructor

typescript
constructor(reason: string)

Parameters:

  • reason: string

StructuredOutputError class

📍 src/core/StructuredOutput.ts:79

Thrown when the model's output cannot be parsed as valid JSON after all repair attempts. Carries the raw output + requested format for debugging — never a silent failure.

Constructor

constructor

typescript
constructor(
    message: string,
    public readonly rawOutput: string,
    public readonly format: ResponseFormat,
    originalError?: Error,
  )

Parameters:

  • message: string
  • rawOutput: string
  • format: ResponseFormat
  • originalError: Error | undefined (optional)

TelegramAPIError class

📍 src/tools/telegram/types.ts:59

Error from Telegram Bot API

Constructor

constructor

typescript
constructor(
    public readonly statusCode: number,
    public readonly errorCode: number | undefined,
    public readonly telegramDescription: string
  )

Parameters:

  • statusCode: number
  • errorCode: number | undefined
  • telegramDescription: string

TelegramConfigError class

📍 src/tools/telegram/types.ts:86

Error for missing Telegram configuration

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

TwilioAPIError class

📍 src/tools/twilio/types.ts:64

Error from Twilio API

Constructor

constructor

typescript
constructor(
    public readonly statusCode: number,
    public readonly twilioCode: number | undefined,
    public readonly twilioMessage: string
  )

Parameters:

  • statusCode: number
  • twilioCode: number | undefined
  • twilioMessage: string

TwilioConfigError class

📍 src/tools/twilio/types.ts:91

Error for missing Twilio configuration

Constructor

constructor

typescript
constructor(message: string)

Parameters:

  • message: string

ContextOverflowBudget interface

📍 src/domain/errors/AIErrors.ts:414

Detailed budget information for context overflow diagnosis

Properties
Property Type Description
actualTokens actualTokens: number; -
maxTokens maxTokens: number; -
overageTokens overageTokens: number; -
breakdown breakdown: Record<string, number>; -
degradationLog degradationLog: string[]; -

ErrorContext interface

📍 src/core/ErrorHandler.ts:15

Context information for error handling

Properties
Property Type Description
agentType `agentType: 'agent' 'task-agent'
agentId? agentId?: string; Optional agent identifier
operation operation: string; Operation that failed
input? input?: unknown; Input that caused the error (optional, for debugging)
metadata? metadata?: Record<string, unknown>; Additional metadata

ErrorHandlerConfig interface

📍 src/core/ErrorHandler.ts:35

Configuration for ErrorHandler

Properties
Property Type Description
logErrors? logErrors?: boolean; Log errors to console/logger. Default: true
includeStackTrace? includeStackTrace?: boolean; Include stack traces in logs. Default: true in development, false in production
transformError? transformError?: (error: Error, context: ErrorContext) => Error; Custom error transformer
retryablePatterns? retryablePatterns?: string[]; Error codes/messages that should be retried
maxRetries? maxRetries?: number; Maximum retry attempts. Default: 3
baseRetryDelayMs? baseRetryDelayMs?: number; Base delay for exponential backoff in ms. Default: 100
maxRetryDelayMs? maxRetryDelayMs?: number; Maximum retry delay in ms. Default: 5000

ErrorHandlerEvents interface

📍 src/core/ErrorHandler.ts:61

Events emitted by ErrorHandler

Properties
Property Type Description
error error: { error: Error; context: ErrorContext; recoverable: boolean }; Emitted when an error is handled
'error:retrying' 'error:retrying': { error: Error; context: ErrorContext; attempt: number; delayMs: number }; Emitted when retrying after an error
'error:fatal' 'error:fatal': { error: Error; context: ErrorContext }; Emitted when an error is fatal (no recovery possible)

IngestionError interface

📍 src/memory/integration/ExtractionResolver.ts:217

Properties
Property Type Description
where where: string; Which mention label / fact index failed.
reason reason: string; -

StepErrorStrategy type

📍 src/domain/entities/Routine.ts:40

Error handling strategy for deterministic steps.

  • 'fail': Abort the routine on step failure (default for preSteps)
  • 'continue': Log the error and continue to next step (default for postSteps)
  • 'skip-remaining': Stop executing remaining steps but don't fail the routine
typescript
type StepErrorStrategy = 'fail' | 'continue' | 'skip-remaining'
Documentation snapshot · 2026-11-02Suggest a correction ↗

Search documentation

Type to search the v2 documentation.

↑ ↓ to navigate Esc to close