Errors and Diagnostics

How to tell UniKVS errors apart and what to do about them.

Policy

All errors extend ErrorBase and support Japanese and English messages. Start by discriminating the kind with instanceof to decide whether to retry or fix the configuration.

import { KeyNotFoundError } from "unikvs";

try {
  await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("Key not found");
  } else {
    throw ex;
  }
}

Client operation errors

Key and open-state errors

Error	Main condition	Resolution
`KeyNotFoundError`	The key does not exist in any Storage.	Check the key name and whether it was stored.
`UniKvsIsNotOpenError`	Operated before opening.	Call `open()` first.
`UniKvsIsOpenError`	Called `open()` while already open.	Avoid double-opening.
`MissingStorageError`	Called `create()` with no Storage registered.	Add `appendStorage()`.
`StorageIsNotOpenError`	A Storage is not open.	Check the `open()` call.
`TransformerIsNotOpenError`	A Transformer is not open.	Check the `open()` call.

Conversion and stream-support errors

Error	Main condition	Resolution
`PluginOperationAggregateError`	Multiple plugin operations failed.	Inspect the wrapped individual errors.
`InvalidInputError`	The input format is invalid.	Check the value type, key definition, and `schema` contents.
`InvalidOutputError`	The output format is invalid.	Check the conversion order, stored data, and `schema` contents.
`ReadableStreamNotSupportedError`	Read streams are not supported.	Check Storage support.
`WritableStreamNotSupportedError`	Write streams are not supported.	Check Storage support.
`EncodableStreamNotSupportedError`	Encode streams are not supported.	Check Transformer support.
`DecodableStreamNotSupportedError`	Decode streams are not supported.	Check Transformer support.

Plugin-specific errors

Storage and utility errors

Package	Error	Main condition
Shared (`@unikvs/core`)	`KeyNotFoundError`	Referenced a missing key. Re-exported from each package.
`@unikvs/memory`	`MemoryInvalidChunkTypeError`	Handled a non-byte chunk.
`@unikvs/utils`	`InvalidFilenameError`	The file name is invalid.
`@unikvs/utils`	`InvalidDirnameError`	The directory name is invalid.

Checksum errors

Package	Error	Main condition
`@unikvs/checksum`	`ChecksumMismatchError`	Hashes do not match.
`@unikvs/checksum`	`ChecksumRequiredError`	The hash for verification is missing.
`@unikvs/checksum`	`ChecksumInvalidVarNameError`	The variable name is invalid.

Aggregate errors

Partial failures such as writes to multiple Storages are grouped into an aggregate error. Inspect each wrapped error to identify the failed destination.

Internationalization

Error messages support Japanese and English. You can use the same mechanism for custom plugins. See the @unikvs/core reference for details.