結論：CLAUDE.mdに5行追加するだけ
Claude Codeを使っていると、長めの出力や複数ツール呼び出しの途中でこのエラーに遭遇することがあります。
API Error: Stream idle timeout - partial response received
レスポンスが途中で切れて、作業内容が消えます。リトライしても同じエラーが繰り返されることが多く、リカバリ手段もありません。2026年4月時点で、Claude CodeのGitHubリポジトリに複数のissueが立っている既知のバグです。
特にClaude Opus 4.7のリリース以降、報告が増えています。GitHub上ではOpus 4.7と1Mコンテキストバリアントを名指しで報告するissueが複数あり、最近のClaude Codeのchangelogにもストリーム処理の改善が継続的に反映されています。Claude Codeだけでなく、通常のClaudeチャットセッションでも長い出力時に発生します。
この記事では、自分が試して効果のあったワークアラウンドを共有します。
なぜ起きるのか
ストリーミング接続がアイドル状態になると、一定時間でタイムアウトが発火します。トリガーになるのは主にこの3つです。
長いファイルの一括書き込み：300行のファイルを1回のツール呼び出しで書こうとするとストリームが詰まる
大量の検索出力：再帰的なgrepで数百行が返ってくるケース
セッションの長期化：20回以上のツール呼び出しを重ねると発生確率が上がる（体感）
長いセッションや大きな出力を伴う作業で特に起きやすい傾向があります。
対処法：CLAUDE.mdに以下を追加
プロジェクトルートのCLAUDE.mdに下記のブロックを追加してください。Claude Codeはセッション開始時にこのファイルを読み込み、制約として適用します。
Stream Timeout Prevention
- タスクは一つずつ実行する。一つ完了して確認してから次に進む。
- 1回のツール呼び出しで150行を超えるファイルを書かない。
長いファイルは複数回に分けて追記・編集する。 - 会話が長くなったら（ツール呼び出し20回超）新しいセッションを開始する。
セッションが長くなるほどエラーが起きやすくなる。 - grep/検索の出力は短く保つ。--includeや-l（ファイル名のみ）フラグを使う。
- タイムアウトが発生したら、同じステップをより短い形でリトライする。
タスク全体を最初からやり直さない。
英語環境の場合はそのまま英語で書いても問題ありません。
Stream Timeout Prevention
- Do each task ONE AT A TIME. Complete one, confirm, then move to the next.
- Never write a file longer than ~150 lines in a single tool call.
If a file will be longer, write it in multiple append/edit passes. - Start a fresh session if the conversation gets long (20+ tool calls).
The error gets worse as the session grows. - Keep individual grep/search outputs short. Use flags like
--include and -l (list files only) to limit output size. - If you do hit the timeout, retry the same step in a shorter form.
Don't repeat the entire task from scratch.
各ルールの狙い
ルール1（一つずつ実行）：「3ファイル作成→テスト→修正」を1つのレスポンスにまとめようとすると出力が巨大になります。1ステップずつ区切ることで、各チャンクが小さくなりストリームが詰まりません。
ルール2（150行制限）：一番効果が大きいルールです。長いファイルの一括書き出しがタイムアウトの最も多いトリガーで、2回に分ければ閾値を下回ります。
ルール3（セッション更新）：ドキュメント化されていませんが、ツール呼び出しが20回を超えたあたりからタイムアウトがほぼ確定で起きるようになります。新しいセッションに切り替えるとリセットされます。
ルール4（検索出力の制限）：再帰grepで500行返ってくるとファイル書き出しと同じくらいストリームが詰まります。-lで一覧だけにするか--includeで絞るだけで回避できます。
ルール5（短縮リトライ）：タイムアウト後に同じプロンプトをそのままリトライすると、同じ場所で同じように詰まります。同じステップを短い形で再試行するのがポイントです。
効果がなかった方法
参考までに、自分が試して効果がなかったものも書いておきます。
CLAUDE_STREAM_IDLE_TIMEOUT_MSの変更：ターミナルCLI用の環境変数で、必ずしも問題を解決しません
ブラウザ変更：Chrome、Firefox、Safariすべてで同じ挙動
モデル変更：OpusでもSonnetでも発生
プロンプトの短縮：プロンプトの長さではなく出力の長さが問題
CLAUDE.mdアプローチが効くのは、出力が生成される前の段階で制約をかけるからです。ストリームが詰まるほど長い出力が最初から生成されなくなります。
関連issue
GitHub Issue #49619: Stream idle timeout during long tool-use turns on Opus 4.7
GitHub Issue #47841: Stream idle timeout on Claude Code Web
GitHub Issue #47252: Ultraplan repeated stream idle timeout errors
GitHub Issue #46987: Stream idle timeout - multiple times today
GitHub Issue #25979: Claude Code hangs indefinitely when API streaming connection stalls
まとめ
CLAUDE.mdに5行追加するだけで、ストリームタイムアウトをほぼ完全に回避できます
最近のchangelogにもストリーム処理の改善が継続的に反映されています。公式修正が入ればこのブロックは外せます
特にClaude Codeで長時間作業する場合は、最初にこの設定を入れておくことを推奨します