Skip to content
Omnio-js
Esc
↑↓navigate↵open⌘Jpreview
On this page

Errors

Exception classes and conditions exposed by Omnio-js.

Overview

Errors derive from ErrorBase and branch into InvalidUsageErrorBase, UnexpectedErrorBase, DbErrorBase, and EmbErrorBase.

Import error classes and metadata types from @omniojs/core. omnio re-exports ChecksumMismatchError.

import {
  DbNotOpenError,
  EntityMissingError,
  InvalidOmnioKeyError,
  OperationAbortedError,
} from "@omniojs/core";
import { ChecksumMismatchError } from "omnio";

Input and key errors

ValiError

The valibot validation error. Import it from valibot, not from @omniojs/core.

It is thrown when constructor or method input does not match the schema. error.issues contains details.

InvalidOmnioKeyError

Thrown when a key is empty, exceeds 1024 characters or 1024 bytes, or is not valid UTF-8.

class InvalidOmnioKeyError extends InvalidUsageErrorBase<{
  input: unknown;
}> {}

name is OmnioInvalidKeyError.

Lifecycle errors

DbNotOpenError

Thrown when an operation runs before open() or after close().

class DbNotOpenError extends DbErrorBase<{
  operation: string;
}> {}

name is OmnioDbNotOpenError.

OperationAbortedError

Used as the reason when close() aborts a running operation.

class OperationAbortedError extends ErrorBase<undefined> {}

name is OmnioOperationAbortedError.

Data errors

EntityMissingError

Thrown when the index has a record but the entity bytes are missing. It indicates data loss or inconsistency, not a race with deletion.

class EntityMissingError extends UnexpectedErrorBase<{
  key: string;
  entityId: string;
  hash?: string;
}> {}

name is OmnioEntityMissingError.

ChecksumMismatchError

Thrown when the SHA-256 of the retrieved bytes does not match the hash stored in the index. This is a @unikvs/checksum error re-exported from omnio.

DbQueryError

Thrown when an index database operation fails.

class DbQueryError extends DbErrorBase<{
  operation: string;
  queryText?: string;
}> {}

name is OmnioDbQueryError.

VectorDimensionMismatchError

Thrown when a vector’s dimensions do not match the index definition.

class VectorDimensionMismatchError extends DbErrorBase<{
  actual: number;
  expected: number;
}> {}

name is OmnioVectorDimensionMismatchError.

EmbeddingModelMismatchError

An error for when an embedding model name does not match the expected value. The normal SQL index path does not use it, but a custom index can.

class EmbeddingModelMismatchError extends DbErrorBase<{
  actual?: string;
  expected: string;
}> {}

name is OmnioEmbeddingModelMismatchError.

Embedding errors

ModelLoadError

Thrown when the embedding model cannot be loaded.

class ModelLoadError extends EmbErrorBase<{
  model: string;
}> {}

name is OmnioModelLoadError.

EmbedFailedError

Thrown when text or image embedding fails.

class EmbedFailedError extends EmbErrorBase<{
  kind: string;
}> {}

name is OmnioEmbedFailedError.

UnsupportedModalityError

Thrown when an embedder is asked for a modality it does not support.

class UnsupportedModalityError extends EmbErrorBase<{
  actual: string;
  supported: readonly string[];
}> {}

name is OmnioUnsupportedModalityError.

Base classes

Class Purpose
ErrorBase Base for every error.
InvalidUsageErrorBase Invalid usage.
UnexpectedErrorBase Unexpected failure.
DbErrorBase Index and database errors.
EmbErrorBase Embedding errors.

Customize messages

Use setErrorMessage to set messages per language.

import { setErrorMessage, DbQueryError } from "@omniojs/core";

setErrorMessage(DbQueryError, ({ operation }) => `Database error: ${operation}`, "en");

Next steps

Was this page helpful?