Desktop のトラブルシューティング

概要

デスクトップアプリ固有の不調とその切り分け。チャットに出る実行時の API エラー（API Error: 500、529 Overloaded、429、Prompt is too long など）は CLI・desktop・web で共通であり、ここではなくエラーリファレンスの担当。

仕様

バージョンの確認

macOS: メニューバーの Claude → About Claude
Windows: Help → About
バージョン番号をクリックするとクリップボードへコピーされる

Code タブで 403 や認証エラー

アプリのメニューからサインアウトして入り直す（最も多い解決策）
有効な有料サブスクリプション（Pro / Max / Team / Enterprise）があるか確認する
CLI では動くのに Desktop で動かない場合は、ウィンドウを閉じるだけでなくアプリを完全に終了してから開き直してサインインする
インターネット接続とプロキシ設定を確認する

起動時に画面が白い・固まる

アプリを再起動する
保留中の更新を確認する（macOS / Windows は起動時に自動更新、Linux は apt）
管理されたネットワークでは、ファイアウォールが CDN ホストを許可しているか確認する
Windows ではイベントビューアーの Windows ログ → Application にクラッシュログが出る

`Failed to load session`

選んだフォルダが既に存在しない、リポジトリが Git LFS を必要としているのに入っていない、ファイル権限でアクセスできない、のいずれか。別のフォルダを選ぶかアプリを再起動する。

インストール済みのツールが見つからない

npm や node などが見つからない場合:

通常のターミナルでそのツールが動くか確認する
シェルのプロファイルが PATH を正しく設定しているか確認する
デスクトップアプリを再起動して環境変数を読み直させる

Git / Git LFS のエラー

Windows ではローカルセッションの開始に Git が必須。 "Git is required" が出たら Git for Windows を入れてアプリを再起動する
"Git LFS is required by this repository but is not installed" が出たら Git LFS を入れ、git lfs install を実行してアプリを再起動する

Windows で MCP サーバーが動かない

トグルが反応しない・接続に失敗する場合は、設定を確認し、アプリを再起動し、タスクマネージャーでサーバープロセスが動いているかを確認し、サーバーのログを見る。

アプリが終了しない

macOS: Cmd+Q。反応しなければ Cmd+Option+Esc の強制終了から Claude を選ぶ
Windows: Ctrl+Shift+Esc のタスクマネージャーで Claude のプロセスを終了する

Windows 固有

インストール後に PATH が更新されない: 新しいターミナルウィンドウを開く。PATH の更新は新しいターミナルセッションにのみ適用される
同時インストールのエラー: 実際には他のインストールが無いのにエラーが出る場合、インストーラを管理者として実行する

CLI で開くと `Branch doesn't exist yet`

cloud セッションはローカルに存在しないブランチを作ることがある。 セッションツールバーのブランチ名をクリックしてコピーし、手元で取得する。

git fetch origin <branch-name>
git checkout <branch-name>

それでも解決しない場合

アプリの Help → Get Support、または Claude のサポートセンター
スタンドアロンの claude CLI でも再現する問題は GitHub Issues で検索・報告する
報告に含めるもの: アプリのバージョン、OS、正確なエラーメッセージ、関連ログ（macOS は Console.app、Windows はイベントビューアー → Windows ログ → Application）
ログには環境のファイルパスなどが含まれる。公開の Issue へ貼る前に中身を確認する

制約・注意点

API エラーは Desktop 固有ではない。 切り分けの最初に、CLI でも再現するかを見る
アプリの「ウィンドウを閉じる」は終了ではない。 認証系の不調では完全終了が必要になる