---
title: "Errors and Diagnostics"
description: "How to tell UniKVS errors apart and what to do about them."
---

## Policy [#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.

```ts
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 [#client-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 [#plugin-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. |

:::danger
Checksum mismatches are mainly caused by corrupted stored data, wrong `vars` specification, or wrong conversion order. Check the order and variables before and after storing.
:::

## Aggregate errors [#aggregate]

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

## Internationalization [#i18n]

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