Errors - core-ai

Overview

core-ai provides a hierarchy of error classes for handling different types of failures when working with language models. All errors extend from CoreAIError and provide structured error information.

Error Hierarchy

CoreAIError
├── ValidationError
│   └── UnsupportedInputModalityError
├── AbortedError
│   └── StreamAbortedError
├── ProviderError
│   ├── ContextLengthExceededError
│   └── RetryableProviderError
│       ├── RateLimitError
│       ├── ModelOverloadedError
│       └── ServiceUnavailableError
└── StructuredOutputError
    ├── StructuredOutputNoObjectGeneratedError
    ├── StructuredOutputParseError
    └── StructuredOutputValidationError

CoreAIError

Base error class for all core-ai errors.

export class CoreAIError extends Error {
    public readonly provider?: string;
    public readonly cause?: unknown;

    constructor(message: string, cause?: unknown, provider?: string) {
        super(message);
        this.name = 'CoreAIError';
        this.cause = cause;
        this.provider = provider;
    }
}

ValidationError

Thrown when core-ai rejects invalid caller input or local request configuration before calling a provider.

export class ValidationError extends CoreAIError {
    constructor(message: string, cause?: unknown, provider?: string) {
        super(message, cause, provider);
        this.name = 'ValidationError';
    }
}

Properties

string

Error message describing what went wrong.

unknown

Optional underlying cause of the error (e.g., network error, API error).

string | undefined

Optional provider context when the error can be attributed to a provider.

string

Error name, always 'ValidationError'.

Example

import { ValidationError } from '@core-ai/core-ai';

try {
    // Some operation
    throw new ValidationError('messages must not be empty');
} catch (error) {
    if (error instanceof ValidationError) {
        console.error('ValidationError:', error.message);
        if (error.cause) {
            console.error('Caused by:', error.cause);
        }
    }
}

UnsupportedInputModalityError

Thrown when user messages include content parts the model does not accept, before the provider call. Extends ValidationError.

export class UnsupportedInputModalityError extends ValidationError {
    public readonly requestedModalities: readonly string[];
    public readonly supportedModalities: readonly string[];
    public readonly unsupportedModalities: readonly string[];
}

Properties

readonly string[]

Modalities present in the user messages.

readonly string[]

Modalities from model.capabilities.modalities.input.

readonly string[]

Requested modalities missing from the model capabilities.

Example

import { UnsupportedInputModalityError, generate } from '@core-ai/core-ai';

try {
    await generate({ model, messages });
} catch (error) {
    if (error instanceof UnsupportedInputModalityError) {
        console.error(error.unsupportedModalities);
    }
}

AbortedError

Thrown when an operation is cancelled via an AbortSignal.

export class AbortedError extends CoreAIError {
    constructor(cause?: unknown, provider?: string) {
        super('operation aborted', cause, provider);
        this.name = 'AbortedError';
    }
}

StreamAbortedError

Thrown when a streaming operation is aborted via an AbortSignal.

export class StreamAbortedError extends AbortedError {
    constructor(cause?: unknown, provider?: string) {
        super(cause, provider);
        this.name = 'StreamAbortedError';
        this.message = 'stream aborted';
    }
}

Example

import { stream } from '@core-ai/core-ai';
import { StreamAbortedError } from '@core-ai/core-ai';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
    const chatStream = await stream({
        model,
        messages: [{ role: 'user', content: 'Write a long story' }],
        signal: controller.signal,
    });

    for await (const event of chatStream) {
        if (event.type === 'text-delta') {
            process.stdout.write(event.text);
        }
    }
} catch (error) {
    if (error instanceof StreamAbortedError) {
        console.log('Stream was cancelled');
    }
}

ProviderError

Error for provider/API failures. Discriminate with subclasses and instanceof. Transient failures extend RetryableProviderError.

export type ProviderErrorOptions = {
    statusCode?: number;
    cause?: unknown;
};

export class ProviderError extends CoreAIError {
    public readonly statusCode?: number;

    constructor(
        message: string,
        provider: string,
        options?: ProviderErrorOptions
    );
}

export class RetryableProviderError extends ProviderError {}

Properties

string

The provider that threw the error (e.g., 'openai', 'anthropic').

number | undefined

HTTP status code if available (e.g., 404, 500, 429).

Classified subclasses

Class	Extends	Extra fields
`ContextLengthExceededError`	`ProviderError`	`maxTokens?`, `actualTokens?`
`RateLimitError`	`RetryableProviderError`	`retryAfterSeconds?`
`ModelOverloadedError`	`RetryableProviderError`	—
`ServiceUnavailableError`	`RetryableProviderError`	—

Each provider wrap*Error helper decides which subclass to throw from SDK-specific fields (error types, status codes, message shapes). Use instanceof to branch in application code — statusCode is for logging and debugging, not for retry decisions. HTTP 429 is not always RateLimitError: billing quota (for example OpenAI insufficient_quota) remains a non-retryable ProviderError, while some capacity signals (for example Azure NoCapacity) map to ModelOverloadedError. RateLimitError.retryAfterSeconds may come from Retry-After, Azure retry-after-ms, or an HTTP-date Retry-After header.

Example

import {
    ContextLengthExceededError,
    generate,
    ProviderError,
    RateLimitError,
    RetryableProviderError,
} from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

const openai = createOpenAI();
const model = openai.chatModel('gpt-5-mini');

try {
    const result = await generate({
        model,
        messages: [{ role: 'user', content: 'Hello' }],
    });
} catch (error) {
    if (error instanceof ContextLengthExceededError) {
        console.error('Context too long', error.maxTokens, error.actualTokens);
    } else if (error instanceof RateLimitError) {
        console.error('Rate limited; retry after', error.retryAfterSeconds);
    } else if (error instanceof RetryableProviderError) {
        console.error(
            `Transient failure from ${error.provider}:`,
            error.message
        );
    } else if (error instanceof ProviderError) {
        console.error(`Provider ${error.provider}:`, error.message);
    }
}

StructuredOutputError

Base class for errors related to structured output generation (objects).

export class StructuredOutputError extends CoreAIError {
    public readonly statusCode?: number;
    public readonly rawOutput?: string;

    constructor(
        message: string,
        provider: string,
        options: StructuredOutputErrorOptions = {}
    ) {
        super(message, options.cause, provider);
        this.name = 'StructuredOutputError';
        this.statusCode = options.statusCode;
        this.rawOutput = options.rawOutput;
    }
}

type StructuredOutputErrorOptions = {
    statusCode?: number;
    cause?: unknown;
    rawOutput?: string;
};

Properties

string | undefined

The raw output from the model that failed to parse/validate.

Example

import { StructuredOutputError } from '@core-ai/core-ai';

try {
    const result = await generateObject({
        model,
        messages: [{ role: 'user', content: 'Generate data' }],
        schema: z.object({ name: z.string() }),
    });
} catch (error) {
    if (error instanceof StructuredOutputError) {
        console.error('Structured output error:', error.message);
        console.error('Provider:', error.provider);

        if (error.rawOutput) {
            console.error('Raw output:', error.rawOutput);
        }
    }
}

StructuredOutputNoObjectGeneratedError

Thrown when the model doesn’t generate an object at all.

export class StructuredOutputNoObjectGeneratedError extends StructuredOutputError {
    constructor(
        message: string,
        provider: string,
        options: StructuredOutputErrorOptions = {}
    ) {
        super(message, provider, options);
        this.name = 'StructuredOutputNoObjectGeneratedError';
    }
}

Example

import { StructuredOutputNoObjectGeneratedError } from '@core-ai/core-ai';

try {
    const result = await generateObject({
        model,
        messages: [{ role: 'user', content: 'Hello' }],
        schema: z.object({ name: z.string() }),
    });
} catch (error) {
    if (error instanceof StructuredOutputNoObjectGeneratedError) {
        console.error('Model did not generate an object');
        console.error('Provider:', error.provider);
    }
}

StructuredOutputParseError

Thrown when the model’s output cannot be parsed as JSON.

export class StructuredOutputParseError extends StructuredOutputError {
    constructor(
        message: string,
        provider: string,
        options: StructuredOutputErrorOptions = {}
    ) {
        super(message, provider, options);
        this.name = 'StructuredOutputParseError';
    }
}

Example

import { StructuredOutputParseError } from '@core-ai/core-ai';

try {
    const result = await generateObject({
        model,
        messages: [{ role: 'user', content: 'Generate user' }],
        schema: z.object({ name: z.string() }),
    });
} catch (error) {
    if (error instanceof StructuredOutputParseError) {
        console.error('Failed to parse model output as JSON');
        console.error('Raw output:', error.rawOutput);
        console.error('Parse error:', error.cause);
    }
}

StructuredOutputValidationError

Thrown when the model’s output doesn’t match the Zod schema.

export class StructuredOutputValidationError extends StructuredOutputError {
    public readonly issues: string[];

    constructor(
        message: string,
        provider: string,
        issues: string[],
        options: StructuredOutputErrorOptions = {}
    ) {
        super(message, provider, options);
        this.name = 'StructuredOutputValidationError';
        this.issues = issues;
    }
}

Properties

string[]

Array of validation error messages from Zod.

Example

import { StructuredOutputValidationError } from '@core-ai/core-ai';
import { z } from 'zod';

try {
    const result = await generateObject({
        model,
        messages: [{ role: 'user', content: 'Generate user' }],
        schema: z.object({
            name: z.string(),
            age: z.number().min(0).max(120),
            email: z.string().email(),
        }),
    });
} catch (error) {
    if (error instanceof StructuredOutputValidationError) {
        console.error('Schema validation failed');
        console.error('Issues:');
        error.issues.forEach((issue) => {
            console.error(`  - ${issue}`);
        });
        console.error('Raw output:', error.rawOutput);
    }
}

Error Handling Patterns

Comprehensive Error Handling

import {
    CoreAIError,
    ProviderError,
    RateLimitError,
    RetryableProviderError,
    StructuredOutputError,
    StructuredOutputNoObjectGeneratedError,
    StructuredOutputParseError,
    StructuredOutputValidationError,
} from '@core-ai/core-ai';

try {
    const result = await generateObject({
        model,
        messages: [{ role: 'user', content: 'Generate data' }],
        schema: z.object({ name: z.string() }),
    });
} catch (error) {
    // Handle specific errors first
    if (error instanceof StructuredOutputValidationError) {
        console.error('Validation failed:');
        error.issues.forEach((issue) => console.error(issue));
        return handleValidationError(error);
    }

    if (error instanceof StructuredOutputParseError) {
        console.error('Parse error:', error.rawOutput);
        return handleParseError(error);
    }

    if (error instanceof StructuredOutputNoObjectGeneratedError) {
        console.error('No object generated');
        return handleNoObjectError(error);
    }

    // Handle provider errors
    if (error instanceof RateLimitError) {
        return handleRateLimit(error);
    }
    if (error instanceof RetryableProviderError) {
        return handleServerError(error);
    }
    if (error instanceof ProviderError) {
        return handleProviderError(error);
    }

    // Handle general core-ai errors
    if (error instanceof CoreAIError) {
        console.error('core-ai error:', error.message);
        return handleCoreAIError(error);
    }

    // Unknown error
    throw error;
}

Retry Logic with Error Handling

async function generateWithRetry<T>(
    fn: () => Promise<T>,
    maxRetries = 3
): Promise<T> {
    let lastError: Error;

    for (let i = 0; i < maxRetries; i++) {
        try {
            return await fn();
        } catch (error) {
            lastError = error as Error;

            if (error instanceof RetryableProviderError) {
                const delay = Math.pow(2, i) * 1000; // Exponential backoff
                console.log(`Retrying in ${delay}ms...`);
                await new Promise((resolve) => setTimeout(resolve, delay));
                continue;
            }

            if (error instanceof ProviderError) {
                // Don't retry non-retryable provider errors
                throw error;
            }

            // Don't retry validation errors
            if (error instanceof StructuredOutputValidationError) {
                throw error;
            }

            // Retry other errors
            if (i < maxRetries - 1) {
                console.log(`Attempt ${i + 1} failed, retrying...`);
            }
        }
    }

    throw lastError!;
}

// Usage
const result = await generateWithRetry(() =>
    generate({
        model,
        messages: [{ role: 'user', content: 'Hello' }],
    })
);

Logging and Monitoring

function logError(error: unknown): void {
    if (error instanceof StructuredOutputValidationError) {
        console.error({
            type: 'validation_error',
            provider: error.provider,
            issues: error.issues,
            rawOutput: error.rawOutput,
        });
    } else if (error instanceof StructuredOutputParseError) {
        console.error({
            type: 'parse_error',
            provider: error.provider,
            rawOutput: error.rawOutput,
        });
    } else if (error instanceof ProviderError) {
        console.error({
            type: 'provider_error',
            provider: error.provider,
            statusCode: error.statusCode,
            message: error.message,
        });
    } else if (error instanceof CoreAIError) {
        console.error({
            type: 'core_ai_error',
            message: error.message,
            cause: error.cause,
        });
    }
}

Graceful Degradation

async function generateWithFallback(
    primaryModel: ChatModel,
    fallbackModel: ChatModel,
    messages: Message[]
): Promise<GenerateResult> {
    try {
        return await generate({
            model: primaryModel,
            messages,
        });
    } catch (error) {
        if (error instanceof ProviderError) {
            console.warn('Primary model failed, using fallback');

            try {
                return await generate({
                    model: fallbackModel,
                    messages,
                });
            } catch (fallbackError) {
                console.error('Fallback also failed');
                throw fallbackError;
            }
        }

        throw error;
    }
}

Best Practices

Always check for specific error types before general ones. Use instanceof checks in order from most specific to least specific.

Don’t retry validation errors (StructuredOutputValidationError) - they indicate a schema mismatch that won’t be fixed by retrying.

Gate retries on RetryableProviderError — the umbrella for transient failures (rate limits, overload, and transient 5xx) — with exponential backoff. Don’t treat every HTTP 429 as retryable: billing quota errors surface as a non-retryable ProviderError.

The rawOutput property in structured output errors is useful for debugging what the model actually generated.

Log error details including provider, status codes, and causes for debugging and monitoring.

​Overview

​Error Hierarchy

​CoreAIError

​ValidationError

​Properties

​Example

​UnsupportedInputModalityError

​Properties

​Example

​AbortedError

​StreamAbortedError

​Example

​ProviderError

​Properties

​Classified subclasses

​Example

​StructuredOutputError

​Properties

​Example

​StructuredOutputNoObjectGeneratedError

​Example

​StructuredOutputParseError

​Example

​StructuredOutputValidationError

​Properties

​Example

​Error Handling Patterns

​Comprehensive Error Handling

​Retry Logic with Error Handling

​Logging and Monitoring

​Graceful Degradation

​Best Practices

Overview

Error Hierarchy

CoreAIError

ValidationError

Properties

Example

UnsupportedInputModalityError

Properties

Example

AbortedError

StreamAbortedError

Example

ProviderError

Properties

Classified subclasses

Example

StructuredOutputError

Properties

Example

StructuredOutputNoObjectGeneratedError

Example

StructuredOutputParseError

Example

StructuredOutputValidationError

Properties

Example

Error Handling Patterns

Comprehensive Error Handling

Retry Logic with Error Handling

Logging and Monitoring

Graceful Degradation

Best Practices