# トラブルシューティング

Canonical page: https://ankiforge.dev/ja/docs/troubleshooting/
Language: ja
Description: インストール、メディア、テンプレート、識別情報、出力のエラーを解決します。

失敗した操作の構造化された `kind` と `code`、原因チェーン、観測結果を使います。表示テキストは人向けであり、変わる可能性があります。操作そのものの失敗と、比較は完了したもののポリシーが公開を阻止した場合は、異なる結果です。

## インストール

| 症状 | 確認すること |
| --- | --- |
| Rust がツールチェーンを拒否する | `rustc --version` を実行し、Rust 1.92 以降を使用します。`cargo tree -i ankiforge` でインストール済みのバージョンを確認します |
| Node がネイティブパッケージを読み込めない | `node -p "process.platform + '/' + process.arch"` と `npm ls ankiforge` を実行し、`npm install --include=optional ankiforge@0.3.1` で再インストールします |
| Node がネイティブ側とラッパーの不一致を報告する | バージョンを揃えます。同じレジストリ版から再インストールするか、同じチェックアウトから両方を再ビルドします |
| Python が拡張を読み込めない | `python -m pip show ankiforge` と `python -m pip debug --verbose` を実行し、インタープリターと wheel の OS/CPU タグを確認します |
| Python がソース配布物を選択する | 対応する wheel・インタープリターを選ぶか、コンパイラーを用意して[ソースからのビルド](https://ankiforge.dev/ja/docs/development/)に従います |

[検証済みの環境](https://ankiforge.dev/ja/docs/compatibility/)、[Node のセットアップ](https://ankiforge.dev/ja/docs/node-quickstart/)、[Python のセットアップ](https://ankiforge.dev/ja/docs/python-quickstart/)を参照してください。

## モデルとノート

| 症状 | 修正方法 |
| --- | --- |
| 無効または空のキー | 安定キーを明示的に指定します。表示名は別です |
| `NOTE.KEY_DUPLICATE` | 論理的なソースレコードごとに一意のキーを1つ割り当てます |
| `NOTE.FIELD_UNKNOWN` | 表示名ではなくフィールドキーで代入します |
| `NOTE.FIELD_REQUIRED` | 追加前に `required()` を指定したフィールドを埋めます |
| `NOTE.MODEL_CONFLICT` | 同じモデルキーには同じ完成済みモデルを再使用します |
| テンプレート参照エラー | 宣言済みキーをテンプレートで使い、元のソースのバイト範囲を確認します |
| HTML が文字として表示される | 意図したマークアップに限って `Content::html` を使います |
| Cloze カードが生成されない | 対応範囲1〜500の番号で `{{c1::answer}}` 構文を指定します |

追加の失敗はアトミックです。ノート・モデルを修正して再試行してください。部分的に登録されたモデルやメディアを取り消す必要はありません。モデルビルダーは `.build()` で完成させてから独自のノートを作成します。

## メディアとテンプレート

| 症状 | 修正方法 |
| --- | --- |
| ファイルのインポートに失敗する | `Media::file` の時点で元ファイルを確認します。成功後の元ファイル削除は可能です |
| MIME と内容が一致しない | バイト列のコンストラクターに実際の MIME タイプを渡します |
| エクスポート名が競合する | 一意で移植可能な名前を選びます。大文字小文字・Unicode 正規化だけの違いも競合します |
| 直接記述した HTML・CSS・スクリプトのリソースが見つからない | モデルの `asset` またはプロジェクトの `add_asset` で宣言します |
| メディアのインポートが上限を超える | インポート前に `MediaLimits.max_bytes` を明示的に増やします |
| ビルド時の検査が上限を超える | その操作の該当する `InspectLimits` カウンターを調整します |
| バンドルの読み込みに失敗する | bundle-v2、明示的なキー、キーを参照するテンプレート、バンドル内のパスを使います |
| 画像穴埋めの矩形が失敗する | デコード後の表示サイズ、有限の座標、一意のマスクキーを確認します |

すべてのノートタイプで文字列の既定の扱いは同じです。メディアノードは依存関係を収集しますが、ファイル名を手書きしただけではバイト列はインポートされません。有効なパッケージでも、使用するコーデック・フォントについてクライアントでの再生確認が必要です。

## 更新と出力

完全な識別情報の証拠を含む、配布時のオリジナル APKG を基準に使います。Anki から再エクスポートしたパッケージにはその証拠が残りません。名前空間の不一致や証拠の破損は、更新ポリシーで許可できません。

完了した比較で `allows_publication == false` となる場合があります。特定のリスク分類を明示的に許可する前に、元の検出事項と証拠を確認してください。すべての結果を一括で許可しないでください。同じ判断を適用するには、実際の更新ビルドにも同じポリシーを渡します。新規作成だけの要求にポリシーを指定するとエラーになります。

一時パスが消えた場合は、すべての読み取り側が終わるまで出力・成果物の所有者を保持してください。レポートと JSON スナップショットは所有者ではありません。永続化に失敗した場合は、エラーの公開段階と耐久性を確認してください。保存先に公開した後でエラーが返ることがあります。[出力の保証](https://ankiforge.dev/ja/docs/build-guarantees/)を参照してください。