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
│   ├── ToolSchemaStrictnessError
│   ├── UnsupportedInputModalityError
│   └── UnsupportedSystemMessagePlacementError
├── AbortedError
│   └── StreamAbortedError
├── ProviderError
│   ├── ContextLengthExceededError
│   ├── MediaCountExceededError
│   │   └── ImageCountExceededError
│   └── 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. This includes schemas core-ai cannot use: a tool’s parameters or a structured output schema that cannot be converted to JSON Schema, a Standard Schema without JSON Schema support, or a value that is neither kind of schema. The message names the tool or schema, and cause holds the schema library’s conversion error when there is one. With tool discovery in use, it also covers the discovery rules:

A tool or discovered tool named core_ai_discover_tools or core_ai_deferred_tools_placeholder, which core-ai reserves.
A discovery call without a tool-discovery message answering it before the next user or assistant message.
A tool-discovery message that answers no discovery call of the preceding assistant message, or answers a call that is already answered.
A discovery call whose id another call of the same assistant message also uses.
A tool-discovery message with both tools and a note.
A tool-discovery message that lists the same tool name more than once.
A discovered tool whose name some provider rejects.
A discovered tool whose parameters are not plain JSON Schema, or not an object schema with type: "object" at the root.
A toolChoice that names a tool outside tools.

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);
        }
    }
}

ToolSchemaStrictnessError

Thrown before the provider request when a strict: true tool is unsupported, exceeds a provider limit, or has a schema outside the strict-capable contract. Extends ValidationError.

type ToolSchemaStrictnessErrorReason =
    | 'unsupported'
    | 'limit-exceeded'
    | 'union-limit-exceeded'
    | 'invalid-schema';

type StrictToolSchemaViolation = {
    toolName: string;
    path: string;
    message: string;
};

class ToolSchemaStrictnessError extends ValidationError {
    readonly providerId: string;
    readonly modelId: string;
    readonly toolNames: readonly string[];
    readonly reason: ToolSchemaStrictnessErrorReason;
    readonly maxStrictTools?: number;
    readonly maxUnionParameters?: number;
    readonly unionParameterCount?: number;
    readonly violations?: readonly StrictToolSchemaViolation[];
}

Properties

string

Provider that rejected the local configuration.

string

Model ID used for capability resolution.

readonly string[]

Tools that requested strict enforcement.

ToolSchemaStrictnessErrorReason

Machine-readable failure category. unsupported means the model does not support strict tool schemas. limit-exceeded means the request contains more strict tools than the provider allows. union-limit-exceeded means the strict tools have more union-typed parameters than the provider allows. invalid-schema means a strict tool’s schema is outside the strict-capable contract.

number | undefined

Provider limit when reason is limit-exceeded.

number | undefined

Provider limit when reason is union-limit-exceeded.

number | undefined

Union-typed parameters across the request’s strict tools when reason is union-limit-exceeded. toolNames then lists the strict tools that have any.

readonly StrictToolSchemaViolation[] | undefined

When reason is invalid-schema, one entry per offending schema path with a fix hint. Also available directly through the exported getStrictToolSchemaViolations() helper.

Example

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

try {
    await generate({ model, messages, tools });
} catch (error) {
    if (error instanceof ToolSchemaStrictnessError) {
        console.error(error.reason, error.toolNames);
        for (const violation of error.violations ?? []) {
            console.error(violation.toolName, violation.path);
            console.error(violation.message);
        }
    }
}

See Strict tool schemas for the strict-capable schema contract and provider support. This error validates request configuration. It does not report invalid arguments returned by a model. Check those with validateToolCall() for Standard Schema tools, or validate them yourself for plain JSON Schema tools, before execution.

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);
    }
}

UnsupportedSystemMessagePlacementError

Thrown when a system message sits where the model does not accept one, before the provider call. The rule comes from model.capabilities.messages.systemPlacement. Extends ValidationError.

export class UnsupportedSystemMessagePlacementError extends ValidationError {
    public readonly placement: 'leading' | 'before-reply' | 'anywhere';
    public readonly issues: readonly SystemMessagePlacementIssue[];
}

type SystemMessagePlacementIssue = {
    index: number;
    reason:
        | 'not-leading'
        | 'must-follow-user-or-tool'
        | 'must-precede-assistant-or-end';
};

Properties

'leading' | 'before-reply' | 'anywhere'

The model’s rule for system messages after the first non-system message.

readonly SystemMessagePlacementIssue[]

Each offending system message, by its index in messages, with the rule it breaks. The error message includes a fix for each one.

To check a conversation without sending it, call the exported getSystemMessagePlacementIssues(messages, placement) helper. See System message placement.

Example

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

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

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?`
`MediaCountExceededError`	`ProviderError`	`maxMedia?`, `actualMedia?`
`ImageCountExceededError`	`MediaCountExceededError`	—
`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,
    ImageCountExceededError,
    MediaCountExceededError,
    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 ImageCountExceededError) {
        console.error('Too many images', error.actualMedia, error.maxMedia);
    } else if (error instanceof MediaCountExceededError) {
        console.error('Too many images or documents', error.maxMedia);
    } 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 a Standard Schema passed as schema to generateObject() or streamObject(). Plain JSON Schema output is never validated by core-ai, so it never raises this error.

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[]

Validation messages from the schema library, each formatted as path.to.key: message. Issues at the root use <root> as the path.

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

​ToolSchemaStrictnessError

​Properties

​Example

​UnsupportedInputModalityError

​Properties

​Example

​UnsupportedSystemMessagePlacementError

​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

ToolSchemaStrictnessError

Properties

Example

UnsupportedInputModalityError

Properties

Example

UnsupportedSystemMessagePlacementError

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