AI Hub

Claude Code

Claude Code「JavaScript heap out of memory」の原因と対処法

公開: / 更新: ・読了目安6分

#エラー対処 #メモリ

Claude Code「JavaScript heap out of memory」の原因と対処法

先に結論: 「JavaScript heap out of memory」は、長時間セッションや.claude.jsonの肥大化などでNode.jsのメモリ上限に達することが原因です。NODE_OPTIONSでのヒープ増量に加え、/compactや/clearでの履歴削減を組み合わせると解消・予防できます。

Claude Codeで「FATAL ERROR: JavaScript heap out of memory」が出て強制終了する場合、原因はNode.jsのメモリ上限(ヒープ)に達したことです。

長時間セッションでの会話履歴の蓄積や、肥大化した.claude.jsonの読み込み、大量ファイルの一括表示が引き金になります。

NODE_OPTIONSでヒープ上限を増やしつつ、/compactや/clearで履歴を減らし、.claude.jsonの肥大化を防ぐことで多くのケースは解消します。

この記事の要点

  • 「FATAL ERROR: JavaScript heap out of memory」は、Node.jsのメモリ上限(ヒープ)に達したことが原因です。
  • NODE_OPTIONS=“—max-old-space-size=4096”のように環境変数でヒープ上限を増やすのが最も即効性のある応急処置です。
  • /compactは会話を要約してメモリ増加を抑え、/clearは会話履歴を丸ごと破棄しより大きな効果があります。
  • .claude.jsonが数MB規模に肥大化すると起動時のJSON解析だけでヒープを使い切ることがあり、バックアップを取ってリセットすると解消します。
  • 再発予防にはclaude —resumeでのセッション分割と、月1回程度の.claude.jsonサイズ確認が有効です。

エラーの症状と原因

このエラーは、次のようなメッセージとともにClaude Codeが突然終了する形で発生します。

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

GitHubのIssuesには次の再現パターンが報告されています。

共通しているのは、会話履歴・状態ファイル・ツール出力のいずれかがNode.jsのヒープ上限を超えてしまう点です。メッセージ配列が解放されないなどClaude Code自体の課題も一因ですが、ユーザー側で打てる対処法も複数あります。

長時間セッション・.claude.jsonの肥大化・大量ファイルの表示・大量のツール呼び出しという4つの原因が、いずれもNode.jsのヒープ上限到達に集約してクラッシュにつながることを示す図

対処法1: NODE_OPTIONSでヒープ上限を増やす

最も即効性があり複数のIssueで有効と報告されているのが、Node.jsのヒープ上限を引き上げる方法です。Claude Code起動前に環境変数NODE_OPTIONSを設定します。

Windowsの場合。

$env:NODE_OPTIONS = "--max-old-space-size=4096"
claude

Macの場合。

NODE_OPTIONS="--max-old-space-size=4096" claude

4096はメガバイト単位のヒープ上限です。搭載メモリに余裕があれば8192(8GB)まで上げても構いません。シェルの起動ファイルに追記すれば以後は自動適用されます。ただしこれはヒープの天井を引き上げる応急処置であり、根本原因を解消するものではありません。次の対処法と組み合わせましょう。

対処法2: /compactや/clearで会話履歴を減らす

長時間セッション由来のクラッシュ(#2278、#25926)には、会話履歴そのものを減らすことが効きます。

/compact

/compactは会話をAIが要約しトークン数を圧縮するコマンドです。定期的に実行すれば履歴に紐づくメモリ増加を抑えられます。大きなタスクが一区切りついたら、次のコマンドで完全リセットする方が確実です。

/clear

/clearは会話履歴を丸ごと破棄してメモリを解放するため、/compactより効果が大きい代わりに文脈も失われます。作業の区切りやタスク切り替えのタイミングで使うと無駄がありません。履歴管理の考え方や/contextでの使用量確認方法は、「Claude Codeのコンテキスト節約術」で詳しく解説しています。

対処法3: .claude.jsonの肥大化を解消する

.claude.jsonは起動履歴などの状態を保存するファイルで、長期間使い続けると数MB規模まで膨れ上がることがあります(#10592では8.4MB・66回分の起動記録が蓄積)。起動のたびに全体を読み込んでパースするため、肥大化すると読み込み処理だけでヒープを使い切りクラッシュします。

ファイルサイズを確認します(Windowsはエクスプローラーのプロパティからでも確認できます)。

(Get-Item "$env:USERPROFILE\.claude.json").Length / 1MB

数MBを超えていればバックアップを取ってリセットします。

mv ~/.claude.json ~/.claude.json.backup

再起動すると新しい.claude.jsonが生成され、多くの場合これでクラッシュが解消します。頻繁に発生する環境では、定期的にサイズを確認し手動でローテーションする運用がおすすめです。

対処法4: セッションを分割し最新版に保つ

数時間にわたる連続セッションは、履歴やツール出力が積み上がり続けるためそれ自体がリスクです。大きなタスクごとにClaude Codeを終了しclaude --resumeで再開する形に分割すると、プロセスがリセットされメモリも解放されます。

claude --resume

あわせて次のコマンドで最新版へのアップデートも確認してください。

claude update

2026年8月時点でも長時間セッションでのメモリ増加はIssueとして報告が続いていますが、バージョンアップで改善されるケースも多いです。動作不良全般の切り分け方は「Claude Codeが動かない時の対処法」も参考にしてください。

再発予防

一度解消しても使い方を変えなければ再発しやすいエラーです。次の3点を習慣にすると再発を防げます。

再発防止の3つの習慣を示す図。区切りのよいところでのセッション分割、/compactや/clearの定期実行、月1回程度の.claude.jsonサイズ確認という3つを習慣にすると再発を防げることを示す図

大きなビルドディレクトリを.gitignoreに含め、巨大なディレクトリは対象を絞って依頼することも、大量ファイル起因のケース(#2099)を避けるうえで有効です。基本的な操作フローは「Claude Codeの使い方完全ガイド」で確認しておきましょう。

よくある質問

NODE_OPTIONSはどのくらいの値に設定すればいいですか?

まずは--max-old-space-size=4096(4GB)から試し、発生するなら8192(8GB)まで引き上げてください。搭載RAMより大きい値を設定しても効果はありません。

.claude.jsonを削除すると何が失われますか?

起動履歴などが失われますが、会話の中身(セッション履歴)とは別ファイルです。認証情報は再ログインで復元できるため、削除して困るデータはありません。

対処してもすぐにまた発生します。どうすればいいですか?

/heapdumpでヒープスナップショットと診断ファイルを取得し、-diagnostics.jsonを添えてGitHubのIssuesか/feedbackで報告してください。長時間セッションでの未解放メモリは、Anthropic側でも継続調査中の領域です。

まとめ

Claude Codeの「JavaScript heap out of memory」は、長時間セッションや.claude.jsonの肥大化、大量ファイルの読み込みでNode.jsのヒープ上限に達することが原因です。

NODE_OPTIONSでのヒープ増量を応急処置としつつ、/compact・/clearでの履歴削減、.claude.jsonのリセット、セッション分割とアップデートを組み合わせれば、多くのケースは解消・予防できます。