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