tsc --noEmit の JavaScript heap out of memory とは、TypeScript の型検査が Node のヒープの上限を超えて落ちる事です。

  • 落ちた時に何を確かめ、max-old-space-size と NODE_OPTIONS でどう当座を逃がすか(Node の公式の文書の範囲で)
  • 上限を上げて終わりにせず、--extendedDiagnostics の Memory used で原因を測って直す手順
  • 社の AI の席が commit の型検査で 8 日に 7 回落ち、上限を上げずに直した時の数字と、途中の落とし穴(社の実測 2026-11-06〜2026-11-13)

当社は開発の仕事の多くを AIエージェントの席に任せています。社の管理画面の API サーバー(TypeScript・Node 26.10.0)のリポジトリでは、席が commit するたびに git の pre-commit(husky)が型検査を撃ちます(社の実測 2026-11-13)。この頁は、その型検査が JavaScript heap out of memory で落ち続けた時に、席が何を確かめ、どう逃がし、どこを直したかの記録です。hook そのものの仕組みは git hooks の頁にまとめています。

落ちた時に出る物と、最初に確かめる事

新しい作業木(worktree)で commit すると、pre-commit の型検査(tsc --noEmit --incremental の全体 1 本)が Node の既定のヒープ上限(約 4GB=4,192MB)を超えて FATAL ERROR: … JavaScript heap out of memory で落ち、husky が code 1 で commit を止めました。hook を通さず素の tsc --noEmit -p . を撃っても同じく落ちました。同じ形が 2026-11-06〜11-13 の 8 日で 7 回、別々の席で起きています(社の実測 2026-11-06〜2026-11-13)。

最初に確かめたのは、機体のメモリが足りないのか、Node のヒープの上限に当たっているのか、です。落ちた時の機体のメモリの圧迫は normal(level 1・空きは 81〜89%)でした(社の実測 2026-11-06・2026-11-12・2026-11-13)。機体には空きが在るのに落ちる=足りないのは機体ではなく、Node が自分に許しているヒープの上限の方だ、と読めます。

  1. 落ちた行に JavaScript heap out of memory が在るかを見る(型の誤りで赤なのとは別の物)
  2. hook を通さずに素の tsc --noEmit を撃ち、hook の外でも落ちるかを見る
  3. その時の機体のメモリの空きを見る。空きが在るなら、Node のヒープの上限を疑う

max-old-space-size と NODE_OPTIONS で当座を逃がす

Node の公式の文書では、--max-old-space-size=SIZE は V8 の old memory の区画の上限を決める旗で、SIZE の単位は MiB です。また、NODE_OPTIONS の環境変数に node の旗を書くと、その旗を付けて起動したのと同じになります(Node.js「Command-line API」2026-11-14 に確認)。tsc は node の上で走るので、tsc の旗ではなく NODE_OPTIONS で渡します。

# その 1 回だけヒープの上限を 8,192MiB に上げて commit を撃ち直す
NODE_OPTIONS=--max-old-space-size=8192 git commit

社の AI の席は、この形で git commit を撃ち直し、hook も素の tsc も通りました。検査したファイルは 4,889(別の回は 2,554)、1 回は 10240 まで上げています。--no-verify で hook を飛ばす事はしていません(社の実測 2026-11-06)。hook を飛ばすと、型の誤りも一緒に見逃すからです。

落とし穴: パイプで切ると、落ちても合格に見える

長い出力を短くしようと tsc … | tail のようにパイプで切ると、シェルが返す終了コード 0 は tail の値で、tsc が落ちていても合格に見えます。社の AI の席はこれで 2 回見落としかけました(社の実測 2026-11-06)。型検査の合否を見る時は、出力を切らずに tsc 自身の終了コードを見ます。

上限を上げずに原因を測る: extendedDiagnostics の Memory used

上限を上げれば通りますが、それは逃げであって直しではありません。席は「上限を上げるだけで閉じない」と決め、終わりの定義を先に置きました。

  • 終わりの定義: NODE_OPTIONS なしで tsc --noEmit --extendedDiagnostics の Memory used が 4,192MB 未満(社の実測 2026-11-13)

extendedDiagnostics は、TypeScript が型検査のどこに時間と資源を使ったかを詳しく出す設定です(TypeScript「TSConfig Reference: extendedDiagnostics」2026-11-14 に確認)。その出力の Memory used と Files を、直す前と後で比べました。

直す前は、既定のヒープでは FATAL(終了コード 134)で、数字が出る所まで行きません。8GB に上げて撃つと、Memory used は 4,574,402K〜4,983,903K でした(社の実測 2026-11-13)。既定の上限の 4,192MB を、上げた状態でも越えて使っていた事になります。

根は、型検査にだけ読み込まれていた型定義だった

測って見つかった根は、googleapis(Google の API の npm)の全部の版の型定義が、素の tsconfig.json の型検査にだけ読み込まれていた事でした。CI の型検査の段は、前から使う版だけに絞ってありました。直しは、CI 側で使っていた paths の指定を tsconfig.json へ持ち上げただけです(社の実測 2026-11-13)。

測った物直す前直した後
NODE_OPTIONS なし(既定のヒープ)
FATAL・終了コード 134
終了コード 0
Memory used
4,574,402K〜4,983,903K(8GB に上げて撃った時)
3,688,262K〜3,744,337K(NODE_OPTIONS なし)
Files
―
4,132
Total time
―
28.11 秒
撃った回数
―
2 回撃って揃った

出典: 社の実測 2026-11-13(社の管理画面の API サーバー・Node 26.10.0・tsc --noEmit --extendedDiagnostics)。

型検査を弱めていないかの確かめ

読み込む型を絞ると、本当は見るべき誤りまで見なくなっていないかが心配になります。席は陰性対照を置いて確かめました。わざと入れた型の誤りは TS2322、絞った型に無い google.drive の呼び出しは TS2339 で、どちらも赤のままでした。また build の出力の JS 2,664 本と .d.ts の差は 0 で、本番の動きは変わりません(社の実測 2026-11-13)。

逃げ方と直し方の比べ

やり方何が起きるか社の AI の席の扱い
--no-verify で hook を飛ばす
commit は通るが、型検査そのものを撃たない
使わなかった
NODE_OPTIONS=--max-old-space-size=8192 を付けて撃ち直す
ヒープの上限が上がり、その回は通る。原因は残る
当座の逃げとして使った
--extendedDiagnostics で測り、読み込む型を絞る
既定のヒープで通る。陰性対照で検査が弱まっていない事を確かめる
直しとして入れた
検査の単位を割る
1 本あたりのメモリが減る
CI の型の段は 3 つに割って各 4,096MB で撃っている。手元は次に上限の際へ寄った時の手

出典: 社の実測 2026-11-06・2026-11-12・2026-11-13。旗の意味は Node.js「Command-line API」(2026-11-14 に確認)。

残る余裕と、次に上限の際へ寄った時の決まり

直した後の Memory used は約 3.74GB で、既定の上限の約 4.19GB に対して残る余裕は約 12% です。席は、次に上限の際へ寄ったら上限を上げずに検査の単位を割る、と決めました。CI の型の段は既に 3 つに割り、各 4,096MB で撃っています(社の実測 2026-11-12・2026-11-13)。CI の作業員の側の話は CI の自前の作業員の頁にあります。

もう 1 つの落とし穴: 手元の緑と CI の赤

tsc -p tsconfig.json は src だけを見て、jest は型を見ません。そのため、手元で型の誤り 0・単体試験が緑でも、CI の「Type-check (src + tests)」が試験のコードの型の誤り 4 件で赤になりました(社の実測 2026-11-13)。手元の型検査がどのファイルを見ているかと、CI の型検査が見ている範囲が同じかを、合否の前に確かめます。

よくある質問

max-old-space-size はいくつにすべきですか?

決まった正解は無く、SIZE は MiB で渡します(Node.js「Command-line API」)。社の AI の席は当座の逃げに 8192(1 回は 10240)を使い、その後は上限を上げずに原因を直して既定のヒープで通るようにしました(社の実測 2026-11-06・2026-11-13)。

NODE_OPTIONS はどこに書きますか?

NODE_OPTIONS は環境変数なので、NODE_OPTIONS=--max-old-space-size=8192 git commit のようにコマンドの前に付ければ、その 1 回の node に効きます(Node.js「Command-line API」)。hook の中の tsc も、この 1 回の撃ち直しで通りました(社の実測 2026-11-06)。

--noEmit なのに、なぜメモリを食うのですか?

noEmit は JavaScript や宣言のファイルを書き出さないだけの設定で、型検査は行われます(TypeScript「TSConfig Reference: noEmit」)。型検査に読み込まれる型定義が多ければメモリを使い、社の例では googleapis の全部の版の型定義が読み込まれていた事が根でした(社の実測 2026-11-13)。

メモリが足りているかは、どう測りますか?

tsc --noEmit --extendedDiagnostics を撃つと Memory used が出ます。社の AI の席は「NODE_OPTIONS なしで Memory used が 4,192MB 未満」を終わりの定義にし、直した後は 3,688,262K〜3,744,337K でした(社の実測 2026-11-13)。

出典

  1. Node.js「Command-line API」https://nodejs.org/api/cli.html (2026-11-14 に確認)
  2. TypeScript「TSConfig Reference: noEmit」https://www.typescriptlang.org/tsconfig/#noEmit (2026-11-14 に確認)
  3. TypeScript「TSConfig Reference: extendedDiagnostics」https://www.typescriptlang.org/tsconfig/#extendedDiagnostics (2026-11-14 に確認)
  4. 社の実測 2026-11-06〜2026-11-13(社の管理画面の API サーバーのリポジトリでの pre-commit の型検査の記録)