---
title: "エラーと診断"
description: "UniKVS のエラーの見分け方と対処の目安を説明します。"
---

## 基本方針 [#policy]

すべてのエラーは `ErrorBase` を継承し、日本語と英語のメッセージに対応しています。まず `instanceof` で種類を判別し、再試行すべきか設定修正すべきか切り分けます。

```ts
import { KeyNotFoundError } from "unikvs";

try {
  await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("キーが見つかりません");
  } else {
    throw ex;
  }
}
```

## クライアント操作のエラー [#client-errors]

**キーとオープン状態のエラー**

| エラー | 主な発生条件 | 対処 |
| --- | --- | --- |
| `KeyNotFoundError` | キーがどのストレージにも存在しません。 | キー名と保存済みかを確認します。 |
| `UniKvsIsNotOpenError` | 未オープンで操作しました。 | `open()` を先に呼びます。 |
| `UniKvsIsOpenError` | オープン済みで再度 `open()` しました。 | 二重オープンを避けます。 |
| `MissingStorageError` | ストレージ未登録で `create()` しました。 | `appendStorage()` を追加します。 |
| `StorageIsNotOpenError` | ストレージが未オープンです。 | `open()` の呼び出しを確認します。 |
| `TransformerIsNotOpenError` | トランスフォーマーが未オープンです。 | `open()` の呼び出しを確認します。 |

**変換とストリーム対応のエラー**

| エラー | 主な発生条件 | 対処 |
| --- | --- | --- |
| `PluginOperationAggregateError` | 複数プラグイン操作が失敗しました。 | 内包された個別エラーを確認します。 |
| `InvalidInputError` | 入力形式が不正です。 | 値の型とキー定義、`schema` の内容を確認します。 |
| `InvalidOutputError` | 出力形式が不正です。 | 変換順序と保存データ、`schema` の内容を確認します。 |
| `ReadableStreamNotSupportedError` | 読み取りストリーム未対応です。 | ストレージの対応状況を確認します。 |
| `WritableStreamNotSupportedError` | 書き込みストリーム未対応です。 | ストレージの対応状況を確認します。 |
| `EncodableStreamNotSupportedError` | エンコード用ストリーム未対応です。 | トランスフォーマーの対応状況を確認します。 |
| `DecodableStreamNotSupportedError` | デコード用ストリーム未対応です。 | トランスフォーマーの対応状況を確認します。 |

## プラグイン固有のエラー [#plugin-errors]

**ストレージとユーティリティーのエラー**

| パッケージ | エラー | 主な発生条件 |
| --- | --- | --- |
| 共通（`@unikvs/core`） | `KeyNotFoundError` | 存在しないキーを参照しました。各パッケージから再エクスポートされています。 |
| `@unikvs/memory` | `MemoryInvalidChunkTypeError` | バイト列以外のチャンクを扱いました。 |
| `@unikvs/utils` | `InvalidFilenameError` | ファイル名が不正です。 |
| `@unikvs/utils` | `InvalidDirnameError` | ディレクトリ名が不正です。 |

**チェックサムのエラー**

| パッケージ | エラー | 主な発生条件 |
| --- | --- | --- |
| `@unikvs/checksum` | `ChecksumMismatchError` | ハッシュが一致しません。 |
| `@unikvs/checksum` | `ChecksumRequiredError` | 検証用ハッシュが不足しています。 |
| `@unikvs/checksum` | `ChecksumInvalidVarNameError` | 変数名の指定が不正です。 |

:::danger
チェックサム不一致は、保存データの破損、変数指定の誤り、変換順序の誤りが主な原因です。保存前後の順序と変数を確認してください。
:::

## 集約エラー [#aggregate]

複数ストレージへの書き込みで部分失敗すると、集約エラーにまとめます。内包された個別エラーを 1 つずつ確認し、失敗した保存先を特定してください。

## 国際化 [#i18n]

エラーメッセージは日本語と英語に対応しています。自作プラグインでも同じ仕組みを使えます。詳細は `@unikvs/core` を参照してください。