Claude Code はサーバーに接続できないとすぐにはエラーを出さず、間隔を倍々に広げながら10回やり直し、約3分後にエラーを出します。2026年11月4日に、Claude Code 2.1.309 で確かめた動きです。

経緯

接続エラーのとき、Claude Code がしばらく何も表示せずに止まったように見えたので、その間に何が起きているかをデバッグのログで確かめました。

環境

• macOS 26.6
• Claude Code 2.1.309(2026年11月4日に確認)

動き

接続できないと、10回やり直して186秒でエラーになる

プロキシを存在しない宛先にして、デバッグのログを書き出しながら、claude -p(対話の画面を開かずに、1回の指示を実行して結果を受け取る使い方)で実行しました。対話画面での表示は、下の「対話画面では Retrying in と出て、esc で止められる」にあります。

terminalCopy code$ HTTPS_PROXY=http://127.0.0.1:9 claude -p "hi" --debug-file retry-debug.log
API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)

エラーが出るまでに186秒かかりました。ログには、リクエストのたびに次の行が出ます。

terminalCopy code[ERROR] API error (attempt 1/11): undefined Connection error.

11 は、最初の1回とやり直しの10回を合わせた数です。

やり直しの間隔は倍々に延び、30〜40秒で止まる

ログの時刻から、やり直しの間隔を計算しました。

7回目までは間隔がほぼ倍になり、8回目からは30〜40秒で止まります。1回目から11回目までで、約186秒でした。

対話画面では Retrying in と出て、esc で止められる

対話画面では、やり直している間、画面の下に次のように表示されます。esc キーで止められます。

terminalCopy codeConnection refused — a firewall or proxy may be blocking it (ECONNREFUSED) · Retrying in 12s · attempt 6/10

claude -p では、この間は何も表示されません。

やり直しを減らすと、すぐにエラーが出る

やり直しの回数は CLAUDE_CODE_MAX_RETRIES で変えられます。0 にすると、約2秒でエラーの文が出ました。

terminalCopy code$ CLAUDE_CODE_MAX_RETRIES=0 HTTPS_PROXY=http://127.0.0.1:9 claude -p "hi"
API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)

公式との違い

公式のエラー一覧には、やり直しの回数(設定のままで10回)と、CLAUDE_CODE_MAX_RETRIES で変えられることが書かれています。間隔の広がり方と、エラーが出るまでに約3分かかることは書かれていません。

対処

原因を早く知りたいとき

CLAUDE_CODE_MAX_RETRIES=0 で実行すると、約2秒でエラーの文が出ます。エラーの文ごとの直し方は、接続エラーの直し方にあります。

スクリプトで使うとき

claude -p を決まった時間で止めたいときは、やり直しの回数を減らします。やり直しの間は何も出力されないので、止まったのか待っているのかが分かりません。

夜間の処理などで、待ってでも終わらせたいとき

CLAUDE_CODE_RETRY_WATCHDOG=1 にすると、サーバーの混雑(429、529)のときに上限なくやり直します(2.1.199 以降、公式のエラー一覧による)。

注意点

止まって見えても、やり直している

対話画面で何も進まないように見えるときは、画面の下の Retrying in の表示を見ます。表示があれば、やり直しの途中です。

参考文献

• Error reference
• Environment variables