Handle errors and cancellation
Classify Omnio exceptions and cancel work safely with AbortSignal.
Input validation errors
Public method inputs are validated with valibot. Invalid values throw ValiError.
import * as v from "valibot";
try {
await omnio.putObject({
key: "notes/a.txt",
data: bytes,
contentType: "text/plain",
tags: new Array(11).fill("tag"),
});
} catch (error) {
if (error instanceof v.ValiError) {
console.error(error.issues);
}
}
At most 10 tags are allowed, and each tag is limited to 128 characters and 128 bytes. Keys are limited to 1024 characters and 1024 bytes.
Common exceptions
| Error | When it occurs |
|---|---|
ValiError |
Input does not match the schema. |
InvalidOmnioKeyError |
The key is empty, too long, or not valid UTF-8. |
DbNotOpenError |
An operation ran before open() or after close(). |
OperationAbortedError |
close() aborted a running operation. |
EntityMissingError |
The index has a record but the entity bytes are missing. |
ChecksumMismatchError |
The SHA-256 of the bytes does not match the index hash. |
DbQueryError |
An index database operation failed. |
ModelLoadError |
The embedding model could not be loaded. |
EmbedFailedError |
Text or image embedding failed. |
UnsupportedModalityError |
The embedder does not support the requested modality. |
error.name is specific, such as OmnioInvalidKeyError or OmnioDbNotOpenError. Use instanceof when you can.
Pass an abort signal
Each method accepts an AbortSignal, either as the last argument or as signal in the input object.
const controller = new AbortController();
const pending = omnio.searchObjects({
query: { text: "seaside" },
signal: controller.signal,
});
controller.abort();
try {
await pending;
} catch (error) {
if (controller.signal.aborted) {
console.log("Search aborted", controller.signal.reason);
}
}
For a time limit, use AbortSignal.timeout().
await omnio.putObject({
key: "large/file.bin",
data: stream,
contentType: "application/octet-stream",
signal: AbortSignal.timeout(30_000),
});
Cancellation by close
close() combines the caller’s signal with the lifecycle signal, so running operations are aborted with OperationAbortedError.
const operation = omnio.getObject("notes/a.txt");
await omnio.close();
await operation.catch((error) => {
if (error instanceof OperationAbortedError) {
// Aborted by close.
}
});
open() and close() time out after 30 seconds when no signal is passed. Pass an explicit signal when the operation may take longer.
Retry
Transient database failures surface as DbQueryError. Before retrying, check whether the operation is idempotent.
getObject,headObject,hasObject,listObjects, andsearchObjectsare easy to retry because they read.putObject,copyObject,renameObject, anddeleteObjectcan create new entities or purge reservations when retried.updateObjectMetadataproduces the same result when retried with the same values.
Localize messages
@omniojs/core exports setErrorMessage. You can replace messages for your application language.
import { DbNotOpenError, setErrorMessage } from "@omniojs/core";
setErrorMessage(DbNotOpenError, () => "The database is not open", "en");