トラブルシューティング

このページでは、よくあるインストール・実行時問題を Q&A 形式で回答します。問題がここにない場合は、関連するログ行を収集して GitHub リポジトリ に issue を開いてください。

ポートがすでに使用中と表示されるのはなぜですか？

ローカルバックエンドはデフォルトで 127.0.0.1:8000 をリッスンします。別のプログラムがそのポートを占有していると、サイドカーは起動できません。競合しているプログラムを終了するか、環境変数 NEOTA_PORT を設定して別のポートでサーバーを起動してください。アプリのエラーメッセージにはポート番号と、競合を解決するために必要な情報が含まれます。

バックエンドのサイドカーが起動しない

デスクトップアプリはバックエンドを組み込みの Node.js サイドカーとして実行します。起動に失敗すると、アプリのウィンドウに接続エラーが表示されます。以下を確認してください:

• 別の NeoTavern インスタンスがすでに実行されていて、ポートを保持している可能性があります。
• データディレクトリが現在の場所で書き込み可能でない可能性があります。
• ウイルス対策ソフトやファイアウォールが組み込みの Node ランタイムをブロックしている可能性があります。

原因に対処したらアプリを再起動してください。アプリがクラッシュループに入った場合は、サードパーティのプラグインとテーマを読み込む前に無効化するセーフモードでの起動を提案します — それを使って復旧してください。

データベースがロックされています

NeoTavern は SQLite を WAL モードとビジータイムアウト付きで使用するため、短時間の同時アクセスは想定され処理されます。「database is locked」エラーが続く場合は、通常、2 つ目のアプリインスタンスが同じデータディレクトリを開いているか、バックアップまたはインポート操作がまだ実行中です。重複インスタンスを閉じ、長時間の操作が終わるのを待ってから再試行してください。

キャッシュをクリアするにはどうすればいいですか？

キャッシュは data/cache/ の下にあり、サムネイル、トークナイザーデータ、プラグインの依存関係ダウンロードなど、すべて再生成可能です。キャッシュをクリアしてもオリジナルは削除されません。オリジナルは data/files/ の下に別途保存されています。設定 → データ のメンテナンスコントロールを使用してキャッシュをクリアしたり、全文検索インデックスを再構築したりできます。どちらの操作も、実行前に削除されるものの数とサイズを確認します。

ログはどこにありますか？

ログは data/logs/server.log に書き込まれ、10 MB でローテーションされます。ログファイルは編集済みです: シークレット、API キー、ユーザーメッセージの内容は決してログに記録されません。コンソール出力もファイルと並行して保持されます。バグを報告するときは、関連するログ行とエラー詳細に表示されるトレース ID を含めてください。

動作するインターフェースに戻るにはどうすればいいですか？

セーフモードを使用してください。セーフモードはサードパーティのテーマとプラグインが読み込まれる前に到達でき、それらを無効化します。テーマやプラグインが壊れた後は、セーフモードがファイルを手で編集せずに組み込みインターフェースを復元します。詳細はテーマ と拡張機能 を参照してください。

送信ボタンが無効なのはなぜですか？

ボタンが無効になるのは具体的な理由がある場合だけで、その理由が隣に説明されます — ほとんどの場合、アクティブなプロバイダーがないか、キャラクターが選択されていません。AI 設定でプロバイダーを接続するかキャラクターを選択すると、ボタンが使えるようになります。クイックスタート を参照してください。