Windows環境でGemini CLIがクラッシュする原因と回避策｜run_shell_commandエラーの正体を徹底解説

Gemini CLIをWindows環境で使用していると、Pythonスクリプト実行時に突然クラッシュする問題に遭遇するケースが報告されている。特に「run_shell_command」が内部エラーで停止する現象は、開発効率に大きな影響を与える。本記事では、この問題の具体的な症状から原因の考察、そして実用的な回避策までを詳しく解説する。

• Windows環境でGemini CLIがクラッシュする原因と回避策｜run_shell_commandエラーの正体を徹底解説
  • Windows環境で発生するrun_shell_commandクラッシュ問題とは
  • エラーの本質：publishプロパティ未定義問題
  • なぜWindowsでのみ発生するのか
    • プロセス起動の違い
    • 非同期処理のタイミング差
    • メッセージバス未初期化問題
  • 実証済みの回避策：PowerShellサブシェルを使う
    • なぜサブシェルで解決するのか
      • 1. 初期化の遅延が発生する
      • 2. 実行コンテキストが変わる
  • 今後の修正が期待されるポイント
  • 開発者が取るべき現実的な対応
    • 1. すべてのコマンドをPowerShell経由に統一
    • 2. CLIのバージョン更新を定期確認
    • 3. エラー発生時のログを保存
  • まとめ：致命的ではないが注意が必要なバグ

Windows環境で発生するrun_shell_commandクラッシュ問題とは

Windows上でGemini CLIを利用してPythonスクリプトを実行しようとすると、「TypeError: Cannot read properties of undefined (reading 'publish')」というエラーが発生し、処理が停止するケースがある。

この問題の特徴は以下の通りだ。

・Pythonスクリプトを直接実行しようとすると失敗する
・「uv run」や「dir」といった基本コマンドでも同様にエラーが出る
・コマンド実行前に内部ツールがクラッシュする

つまり、問題はコマンドそのものではなく、Gemini CLI内部の実行処理にあると考えられる。

エラーの本質：publishプロパティ未定義問題

今回のエラーの核心は、「publish」というプロパティが未定義の状態で呼び出されている点にある。

このエラーが意味するのは、以下のような内部状態の不整合だ。

・メッセージ送信機構（内部バス）が初期化されていない
・CLI内部の状態管理が不完全なまま処理が開始されている
・ツール実行時のライフサイクルが崩れている

特にWindows環境では、プロセス生成のタイミングや初期化順序が他のOSと異なるため、このような問題が顕在化しやすい。

なぜWindowsでのみ発生するのか

この問題がWindows特有である可能性は高い。その理由として、以下の要因が考えられる。

プロセス起動の違い

Windowsでは、プロセス生成時の環境構築や初期化処理がUnix系OSとは異なる。そのため、CLI内部の依存関係が完全に準備される前に処理が走る可能性がある。

非同期処理のタイミング差

Gemini CLIは内部的に非同期処理を多用していると考えられる。Windows環境ではスレッドやイベントループの挙動が微妙に異なり、初期化タイミングにズレが生じる。

メッセージバス未初期化問題

今回のエラーから推測される最も有力な原因は、内部メッセージバスの未初期化である。つまり、ログや確認メッセージを送信する仕組みが準備されていない状態で「publish」が呼ばれている。

実証済みの回避策：PowerShellサブシェルを使う

この問題には、すでに実用的な回避策が存在する。それが「PowerShellサブシェル経由でコマンドを実行する方法」だ。

具体的には、以下のようにコマンドをラップする。

powershell -NoProfile -Command "uv run python src/python/process.py"

この方法を使うと、同じコマンドでも正常に実行されることが確認されている。

なぜサブシェルで解決するのか

この回避策が有効な理由は主に2つある。

1. 初期化の遅延が発生する

PowerShellを経由することで、内部処理にわずかな遅延が生まれる。この遅延によって、CLI内部の初期化が完了する時間が確保される。

2. 実行コンテキストが変わる

サブシェルを使用することで、プロセスの実行環境が変わり、問題のあるコードパスを回避できる可能性がある。

今後の修正が期待されるポイント

この問題は根本的にはCLI側のバグであり、将来的な修正が期待される。特に重要な改善ポイントは以下の通りだ。

・run_shell_command実行前の初期化チェック強化
・publish呼び出し前のnullチェック追加
・Windows環境でのプロセス生成処理の見直し

これらが改善されれば、ユーザー側での回避策は不要になるだろう。

開発者が取るべき現実的な対応

現時点でこの問題に直面している開発者は、以下の対応を取るのが現実的だ。

1. すべてのコマンドをPowerShell経由に統一

安定性を重視するなら、最初からすべてのコマンドをサブシェルで実行する運用にするのが最も確実だ。

2. CLIのバージョン更新を定期確認

ナイトリービルドを使用している場合は特に、修正が入る可能性が高いため、最新バージョンのチェックは欠かせない。

3. エラー発生時のログを保存

同様の問題が再発した場合に備え、ログを記録しておくことで原因特定が容易になる。

まとめ：致命的ではないが注意が必要なバグ

今回のrun_shell_commandクラッシュ問題は、一見すると致命的な不具合に見えるが、回避策が存在するため開発を完全に止める必要はない。

重要なのは以下のポイントだ。

・原因はコマンドではなくCLI内部の初期化不備
・Windows環境で特に発生しやすい
・PowerShell経由でほぼ確実に回避可能

今後のアップデートでの修正が期待されるが、それまでは適切な回避策を取りながら運用することが現実的な選択と言える。

この問題を正しく理解しておけば、同様のエラーに遭遇しても冷静に対処できるはずだ。