トラブルシューティング

サバちゃんの運用中によく遭遇する問題と、実際のコードの動作に基づく解決手順。

トラブルシューティング

このドキュメントは、ユーザーが実際に経験する症状ごとに整理し、デーモンのコードがどう動くか と解決の手順を説明します。コマンドの例とパスは Windows が基準です。Linux ではデータフォルダーが ~/.config/saba-chan です。


1. デーモンが起動しない / GUI が接続できない

1.1 ポートの競合 / デーモンがすでに動いている

デーモン(saba-core)は既定でポート 57474 を、127.0.0.1 でのみ待ち受けます。

  • PC ごとに動くデーモンは1つだけです。すでにデーモンが動いていれば、新しく起動したデーモンはすぐに終了し、GUI と CLI は動いているほうに接続します。
  • 別のプログラムがポートを使っている場合、デーモンは2秒間隔で10回再試行してから終了します。
# Windows: 使用しているプロセスを確認
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
  • デーモンが生きているかどうかは、トークンなしで http://127.0.0.1:57474/health から確認できます。saba-chan-cli daemon status でも同じ情報を確認できます。
  • 応答しないデーモンが残っている場合は、saba-chan-cli daemon stop で停止します。それでも消えない場合は、Stop-Process -Name saba-core -Force を実行します。
  • ポートを変更する必要がある場合は、config.json の gui.ipcPort を編集して再起動します。または SABA_IPC_PORT=57480 のような環境変数を設定します。

1.2 IPC トークンの不一致

デーモンは起動するたびに新しい .ipc_token を作成します。認証に失敗する(401)と、GUI と CLI はトークンファイルを読み直して1回再試行するため、通常は自然に解決します。

「認証失敗」が繰り返される場合:

  • GUI とデーモンが同じデータフォルダーを見ているか確認してください。SABA_DATA_DIR や SABA_TOKEN_PATH を片方にだけ設定していると、トークンファイルの場所が食い違います。
  • GUI を完全に終了してから、もう一度起動してください。

2. サーバーの起動/停止がおかしい

2.1 停止を押してもしばらく何も起きない

それは正常な場合があります。デーモンは次の順で判断します。

  1. コンソールのあるサーバーでは、モジュールの stop_command をコンソール(stdin)に送ります。Palworld のようにコンソールのないゲームでは、モジュールが REST でサーバーに保存と終了を要求します。
  2. サーバーが自分で終了するのを待ちます。既定は 30秒 で、モジュールは module.toml の [config] stop_timeout で変更でき、ユーザーはサーバー画面の サバちゃん タブの 停止の待機時間 でサーバーごとに変更できます。ワールドが大きくて保存に時間がかかるときは長くしてください。
  3. それでも生きていれば、強制終了します。
  4. 停止後 30秒 の間は、クラッシュの検出が抑制されます。

いつも強制終了になってしまう場合は、サーバーが停止コマンドを受け取れていません。サーバーのコンソールに停止コマンドが表示されているか確認してください。例:Minecraft の stop、Zomboid の quit。

2.2 サーバーが何度も立ち上がる

サーバーが終了すると、デーモンは原因を 手動で停止 / ゲーム内で停止 / クラッシュ / 原因不明 に分類します。既定では クラッシュの場合にのみ 自動で再起動します。待ち時間は5秒から始まって毎回2倍になり、10分以内に3回を超えて再起動すると、それ以上は再起動しません。

解決方法:

  • サーバー画面の「最近の終了履歴」で分類を確認します。
  • 再起動を止めるには、サーバー画面の サバちゃん タブの「自動再起動」で「クラッシュ時に再起動」をオフにします。「原因不明の終了でも再起動」をオンにしていた場合は、それも確認してください。
  • サーバーのコンソールログ(instances\<id>\logs\)でクラッシュの原因を確認します。Java の OOM(OutOfMemoryError)なら、メモリの設定を増やしてください。

2.3 起動時に「ポート競合」エラーが出る

起動前のチェックで、サーバーのポートが動作中の別のインスタンスや別のプログラムに使われていることが見つかりました。たいていは以前のプロセスが残っているか、別のゲームサーバーが同じポートを使っています。

  • そのポートを使っているプロセスを見つけて停止します。
  • それができない場合は、インスタンスの設定でポートを変更して再び起動します。
  • チェック自体は GUI の設定の「ポート競合チェック」(gui.portConflictCheck)でオフにできますが、おすすめしません。

2.4 「規約への同意が必要です」(Minecraft EULA など)

モジュールが規約(例:Minecraft EULA)を宣言しているゲームでは、サーバーを起動する前に規約を読んで同意する必要があります。同意するまでは、起動が agreement_required でブロックされます。

  • GUI でサーバーを起動すると表示されるダイアログで規約を読み、チェックボックスにチェックを入れて起動します。
  • Discord から規約に同意することはできません。PC のサバちゃんで一度同意すれば、Discord からもサーバーを起動できるようになります。

2.5 サーバー設定の保存が拒否される

  • unknown_setting: そのキーは、インスタンス共通のフィールドでもモジュールが宣言した設定でもありません。タイプミスか、別のゲームの設定です。
  • validation_failed / invalid_format: 値の範囲や形式がモジュールの宣言と合っていません。エラーに示されたフィールドを修正してください。
  • 「設定は保存しましたが、ゲームの設定ファイルに書き込めませんでした」: 設定は保存されましたが、モジュールがゲームの設定ファイルを編集できませんでした。ゲームのファイルが別のプログラムにロックされていないことを確認して、もう一度保存してください。

2.6 未検証のコンポーネントが実行できない

公式カタログからインストールされていないモジュールやエクステンション、あるいはその後にファイルが変更されたものは「未検証」と表示されます。サバちゃんはこれらをウイルス対策でスキャンしません。Windows では AppContainer、Linux では bubblewrap で隔離して実行し、隔離できない環境(bubblewrap がない、または使えない Linux、macOS)では現在のファイルに同意した後にのみ実行します。実行がブロックされた場合は、次のいずれかのコードが表示されます。

コード意味対処
launch_outside_instanceモジュールがサーバーフォルダーの外にあるプログラムを実行しようとしたモジュールの入手元を確認する
sandbox_unavailableこの PC で隔離環境を用意できなかった下記を参照

sandbox_unavailable の場合、GUI は「隔離せずに実行しますか?」と確認します。許可するのは 信頼できるコンポーネントだけ にしてください。許可すると、そのコンポーネントはあなたのアカウントの権限ですべてのファイルとネットワークにアクセスできます。同意できるのはこの PC 上だけで、コンポーネントのファイルが変わると再び確認されます。同意は 設定 → セキュリティ →「隔離せずに実行」で取り消せます。

最も確実な解決策は、モジュールやエクステンションを公式カタログから再インストールすることです。検証済みのコンポーネントはこれらのチェックを経ません。


3. インストール / アップデートの問題

3.1 インストールが途中で失敗する

  • インストーラーが止まると、エラー画面に原因コード(fetch_failed、download_failed、extract_failed、elevation_failed、installer_outdated)とログのパスが表示されます。ログは %TEMP%\saba-chan-installer.log に書き込まれます。
  • installer_outdated は、インストーラーが最新のリリースより古いことを意味します。最新のインストーラーをダウンロードして実行してください。
  • ネットワークの問題なら、接続を確認してから 再試行 をクリックするか、インストーラーをもう一度実行してください。
  • Python ランタイムの準備中に失敗しても、インストールは止まりません。デーモンが初回起動時にもう一度準備し、インストーラーを再実行すると、破損したランタイムを削除して新たにダウンロードします。

3.2 サーバーのインストールの進行状況が表示されない、または止まっている(モジュール開発者向け)

サーバーのインストールの進行状況は GET /api/provision-progress/:name で取得できます。

  • モジュール/エクステンションが、進行状況を PROGRESS:{json} の形式で stderr に出力しているか確認します。
  • JSON が正しいか確認します(message 内のダブルクォートと改行はエスケープします)。
  • 成功した進行状況は完了の5秒後に削除されるため、ポーリングが遅すぎると、すでに空になっています。失敗した進行状況はユーザーが閉じるまで残り、新規作成したサーバーだった場合は、閉じるとそのインスタンスが削除されます。

3.3 アップデートが適用されない

アップデートは、サバちゃんのリレーが提供する署名済みのリリース情報と照合して確認され、適用前にすべてのファイルのハッシュが検証されます。署名やハッシュが一致しなければ、何も適用されません。

  • アップデート後に一部の項目を更新できなかったという通知が出た場合は、それをクリックするとどの項目が失敗したかを確認できます。
  • GUI の設定でもう一度アップデートを確認し、適用してください。
  • デーモン、GUI、インストーラー自体を置き換えるアップデートは、デーモンの終了後にインストーラー(saba-chan-installer)が適用します。適用中はサバちゃんを再起動しないでください。
  • それでも解決しない場合は、サバちゃんを終了し、updates\ フォルダーを空にしてからもう一度試してください。

4. Discord ボット / クラウドのペアリング

4.1 ボットが応答しない

  • プレフィックス(既定 サバちゃん)、スペース、サーバー名、コマンドの順に書きます。例:サバちゃん minecraft status。
  • GUI でペアリングを完了し、.node_token が保存されている必要があります。
  • サバちゃん(デーモン)が動いている必要があります。ボットはクラウドで動作しますが、コマンドを実行するのはこの PC のデーモンです。
  • デーモンがリレーに接続できない場合は、GUI の 設定 → トラブルシューティング →「診断情報」で最近の警告を確認してください。「older than relay minimum」と表示されている場合は、サバちゃんをアップデートしてください。
  • 公式ボットが Discord サーバーに招待されていて、スリープしていないことを確認してください。スリープしている場合は /saba wake で起こします。

4.2 ペアリングコードが「期限切れ」

ペアリングコードの有効期間は5分だけです。GUI で新しいコードを発行してください。

4.3 リレーへの接続が 401 で拒否される

エラー原因対処
TOKEN_REPLACED別の場所でペアリングする際に 再接続 でこの PC が選ばれ、この PC のトークンが置き換えられたこの PC を使い続けたい場合は、もう一度ペアリングする
INVALID_TOKEN / NODE_NOT_FOUND.node_token が間違っているか、サーバー側で削除されたもう一度ペアリングする(既存のトークンは無効になる)
MISSING_TOKEN / INVALID_TOKEN_FORMATトークンファイルがない、または形式が正しくないもう一度ペアリングする

4.4 音楽コマンドが動かない

  • GUI の Discord ページで、その Discord サーバーの設定で音楽が有効になっているか確認します。
  • コマンドを出す人がすでに Discord のボイスチャンネルにいる必要があります。ボットがボイスチャンネルに参加できない場合は、ボットのチャンネル権限を確認してください。
  • 再生は公式の音楽サーバーが担当するため、PC に ffmpeg や yt-dlp は不要です。

4.5 リモートデーモンにつながらない

表示対処
そのPCはリモート接続を開いていませんサーバー PC で設定 → 接続 → リモートデーモンのリモート接続を受け付けるがオフになっています。オンにして保存します
リモートデーモンに届きませんでしたサーバー PC とそのサバちゃんが起動していて、インターネットにつながっているか確認します。直接届かないときはサバちゃんクラウド経由でつなぐので、ポート開放は必須ではありません
このPCはDiscordにつないでいません2 台とも同じ Discord アカウントでペアリングします
リモートデーモンがこのPCを受け付けなくなりましたサーバー PC 側で接続を切りました。手元の PC で 接続 を押し直します
ポートはすでに使われていますほかのプログラムが同じポートを使っています。ポートを変えます
そのPCで直接行う必要がありますアップデートや自動起動のように、リモートではできない操作です

4.6 サバちゃんウェブのリンクが開かない

  • リンクは 1 回だけ、5 分以内に開けます。/saba web で新しいリンクを取ります。
  • PC に接続できませんでした と出たら、PC のサバちゃんが起動していて最新バージョンか確認します。
  • PC なしで開いたリンクでは、サーバー・モジュール・PC のメニューがロックされています。アプリをインストールして /saba connect を行ってから、新しいリンクを取ります。
  • タブを閉じたり再読み込みしたりするとセッションは終わります。これは正常な動作です。

5. データ / 設定の復旧

5.1 config.json が壊れた

  • デーモンは壊れた config.json を config.json.corrupt-<タイムスタンプ> として退避し、config.json.bak(直前の正常なコピー)から自動で復元します。
  • .bak もないか壊れている場合は、既定値で起動します。Discord 連携の設定を含むすべての設定がリセットされるため、退避された .corrupt- ファイルを参考に、必要な値を GUI で入力し直してください。
  • サーバーの一覧(instances\)と .node_token は config.json とは別なので、保持されます。

5.2 完全なリセット

1. サバちゃんの GUI、CLI、デーモンを終了する
2. %APPDATA%\saba-chan フォルダー全体をバックアップしてから削除する
3. サバちゃんを起動する → 既定値で再構築される

注意:既定の場所にサーバーをインストールした場合、ゲームサーバーのファイルとバックアップは %APPDATA%\saba-chan\instances\ の中にあり、一緒に削除されます。ゲームのファイルが残るのは、このフォルダーの外にサーバーフォルダーを選んだ場合だけです。


6. ログはどこにある?

場所内容
%APPDATA%\saba-chan\logs\saba-chan-*.logGUI のログ。GUI が起動したデーモンの出力も含む
GUI のデーモンのコンソールウィンドウデーモンのログ(メモリ上のバッファ、直近 10,000 行)
GUI の 設定 → トラブルシューティング → 診断情報デーモンの状態と最近の警告/エラー。パスワードやトークンは含まない
%APPDATA%\saba-chan\instances\<id>\logs\サーバーのコンソールログ(console.log、sessions\)
GUI のコンソールタブインスタンスごとのゲームサーバーの出力
%APPDATA%\saba-chan\audit.logサーバーの起動・停止・コマンドの記録(送信元付き、秘密情報はマスク)
%TEMP%\saba-chan-installer.logインストーラーのログ

デーモンを直接実行する場合は、RUST_LOG 環境変数でデーモンのログレベルを変更できます(既定 info)。


7. 不具合報告のチェックリスト

新しい Issue を作成する前に、次の内容を確認して添付してください。

  1. サバちゃんのバージョン(saba-chan-cli version、または GUI の診断情報)。
  2. 再現手順。
  3. 関連するログ(タイムスタンプで絞り込んだ抜粋)。GUI の診断情報の「コピー」の出力も役立ちます。
  4. OS / ビルド(例:Windows 10 x64 21H2)。
  5. トークンファイル(.ipc_token、.node_token)やその内容は絶対に添付しないでください。

リポジトリ: