トラブルシューティング

失敗した操作の構造化された 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・インタープリターを選ぶか、コンパイラーを用意してソースからのビルドに従います

検証済みの環境、Node のセットアップ、Python のセットアップを参照してください。

モデルとノート

症状	修正方法
無効または空のキー	安定キーを明示的に指定します。表示名は別です
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 スナップショットは所有者ではありません。永続化に失敗した場合は、エラーの公開段階と耐久性を確認してください。保存先に公開した後でエラーが返ることがあります。出力の保証を参照してください。