Node.jsのheap out of memoryの原因と直し方
大きなログや CSV のファイルを Node.js で読み込んで集計するスクリプトが、FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory で落ちることがあります。原因は、JavaScript のオブジェクトを置くメモリー(ヒープ)が、V8 の上限に達したことです。CSV や JSON Lines のように1行に1件の形式なら、1行ずつ読んで処理するように書き換えると、全件をメモリーに持たずに済み、上限をかなり下げてもエラーは出なくなります。すぐに書き換えられないときは、--max-old-space-size で上限を上げても消えます。
私は、300万行の JSON Lines(1行に1件の JSON を書いた形式)のファイルを全件読み込んで集計するスクリプトでこのエラーを起こし、出た全文と、2つの直し方でエラーが消えることを確かめました。
検証環境は Ubuntu 24.04(メモリー 16 GB)で、Node.js 24.22.1 と 22.23.4 を使いました。Windows と macOS での動き、Docker などのコンテナーでメモリーを制限した場合、webpack や Next.js のビルドなどツールの中で出る同じエラーは試していません。
エラーの全文(Node.js 24.22.1)
検証用に、次の形の行が300万行並んだ orders.ndjson(約136 MB)を作りました。
{"id":1,"user":"user-1","price":37}
{"id":2,"user":"user-2","price":74}
{"id":3,"user":"user-3","price":111}
これを集計するのが、次の sum-all.mjs です。ファイル全体を文字列として読み込み、行に分けて全件を JSON.parse してから、ユーザーごとに金額を足し合わせます。
// ファイル全体を読み込み、全件を配列にしてから集計する
import { readFileSync } from 'node:fs';
const text = readFileSync('orders.ndjson', 'utf8');
const orders = text.trimEnd().split('\n').map((line) => JSON.parse(line));
const totals = new Map();
for (const o of orders) totals.set(o.user, (totals.get(o.user) ?? 0) + o.price);
console.log('orders:', orders.length, 'users:', totals.size, 'user-1:', totals.get('user-1'));
検証環境のヒープの上限は既定で 8 GB ほどあり(後で確かめ方を書きます)、このファイルではエラーになりません。そこで、上限を 256 MiB に下げて、データが上限を超える状況を作りました。すると、次のように出て止まりました。
$ node --max-old-space-size=256 sum-all.mjs
<--- Last few GCs --->
[1649:0x45bee000] 579 ms: Scavenge 219.9 (236.5) -> 219.9 (284.5) MB, pooled: 0 MB, 40.30 / 0.00 ms (average mu = 0.890, current mu = 0.890) allocation failure;
[1649:0x45bee000] 928 ms: Mark-Compact 274.8 (307.9) -> 274.8 (403.4) MB, pooled: 0 MB, 243.11 / 0.00 ms (average mu = 0.682, current mu = 0.481) allocation failure; scavenge might not succeed
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----
1: 0x942e80 [node]
2: 0x75f71e node::OOMErrorHandler(char const*, v8::OOMDetails const&) [node]
3: 0xc9a1e0 [node]
4: 0xc9a2cf [node]
5: 0xf3dba5 [node]
6: 0xf4f50c [node]
7: 0xf249c3 [node]
8: 0xef9e54 [node]
9: 0xf095a9 [node]
10: 0x10b2486 [node]
11: 0x10b5d01 [node]
12: 0x10b71f9 [node]
13: 0x10b868a [node]
14: 0x10b8915 [node]
15: 0xd2315b [node]
16: 0x1b068f6 [node]
大事なのは FATAL ERROR の行で、「ヒープの上限に達し、メモリーを確保できなかった」という意味です。その上の Last few GCs は、落ちる直前のガベージコレクション(GC、使われなくなったメモリーを片付ける処理)の記録です。Mark-Compact 274.8 (307.9) -> 274.8 (403.4) MB の行では、GC の前も後も 274.8 MB のままで、片付けても空きが作れなかったことが分かります。[1649:0x45bee000] はプロセス番号とアドレスで、実行するたびに変わります。
Native stack trace 以下は Node.js の内部の関数の場所で、自分のコードのどこで止まったかは書かれていません。プロセスはその場で終わり、終了コードは 134 でした。シェル(bash)は Aborted と表示しました。
Node.js 22.23.4 でも、FATAL ERROR の行は一字一句同じでした。違ったのは周りの部分で、Last few GCs の記録の書き方が変わり、<--- JS stacktrace ---> という見出しが入り、Native stack trace には v8::internal::V8::FatalProcessOutOfMemory などの関数の名前が出ました。
上限がいくつになっているかを確かめる
いま動いている Node.js のヒープの上限は、v8 モジュールの getHeapStatistics() の heap_size_limit で分かります。MiB にして表示すると、次のとおりでした。
$ node -p 'require("v8").getHeapStatistics().heap_size_limit / 1024 / 1024'
8384
同じマシンでも、Node.js 22.23.4 では 8240 と、バージョンで違いました。エラーが出た環境で、まずこの値を見ておくと、上限をどれだけ上げればよいかの目安になります。
--max-old-space-size=256 を付けて同じコマンドを実行すると、448 と出ました。公式ドキュメントの --max-old-space-size の説明によると、このオプションで決めるのは V8 のヒープのうち「old space」と呼ばれる部分の上限です。ヒープ全体の上限である heap_size_limit は、指定した 256 より大きい値でした。
1行ずつ読んで集計する(根本的な直し方)
sum-all.mjs がメモリーを使うのは、ファイルの中身を丸ごと文字列にしたうえで、300万件のオブジェクトを配列に入れたまま持っているからです。集計に必要なのはユーザーごとの合計だけなので、1行読んだら足し合わせて、その行は捨てるように書き換えます。
公式ドキュメントにある、readline でファイルを1行ずつ読む例と同じく、fs.createReadStream で開いたファイルから readline でインターフェースを作り、for await...of で1行ずつ取り出すのが sum-stream.mjs です。
// 1行ずつ読み、読んだそばから集計する(全件を配列に持たない)
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
const rl = createInterface({ input: createReadStream('orders.ndjson'), crlfDelay: Infinity });
let count = 0;
const totals = new Map();
for await (const line of rl) {
if (!line) continue;
const o = JSON.parse(line);
totals.set(o.user, (totals.get(o.user) ?? 0) + o.price);
count++;
}
console.log('orders:', count, 'users:', totals.size, 'user-1:', totals.get('user-1'));
エラーが出たときと同じ 256 MiB の上限で実行すると、最後まで動いて、sum-all.mjs を既定の上限のまま動かしたときと同じ集計結果が出ました。上限を 32 MiB まで下げても同じでした。次の出力にある maxRSS の行は、メモリーの使用量の最大値を表示する peak.mjs(後で説明します)を読み込ませて出したものです。
$ node --import ./peak.mjs --max-old-space-size=32 sum-stream.mjs
orders: 3000000 users: 1000 user-1: 6111000
maxRSS: 70 MiB
同じ 32 MiB で sum-all.mjs を実行すると、FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory で終わりました(終了コード 134)。Node.js 22.23.4 でも、sum-stream.mjs は上限 32 MiB で最後まで動きました。
どれだけメモリーを使ったかも比べました。終了するときに process.resourceUsage() の maxRSS(プロセスが使ったメモリーの最大値)を表示する小さなファイル peak.mjs を --import で読み込ませ、上限を既定のままにして2つを実行しました。

sum-all.mjs は 654 MiB、sum-stream.mjs は 70 MiB でした。全件を配列に持つ書き方では、ファイルの大きさ(約136 MB)の4倍以上のメモリーを使いました。1行ずつ読む書き方なら、ファイルが大きくなっても、持っておくのは途中の合計だけです。
ヒープの上限を上げる
書き換える時間がないときや、どうしても全件をメモリーに置く必要がある処理では、上限を上げます。256 MiB で落ちた sum-all.mjs は、1024 MiB にすると最後まで動きました。
$ node --max-old-space-size=1024 sum-all.mjs
orders: 3000000 users: 1000 user-1: 6111000
node のコマンドを直接書き換えにくいときは、環境変数 NODE_OPTIONS に書いても効きます。
$ NODE_OPTIONS=--max-old-space-size=1024 node sum-all.mjs
orders: 3000000 users: 1000 user-1: 6111000
効いているかどうかは、先ほどの heap_size_limit で確かめられます。NODE_OPTIONS=--max-old-space-size=1024 のときは 1216 になりました。NODE_OPTIONS と node の後ろの両方に書いた場合は、公式ドキュメントの NODE_OPTIONS の説明のとおりコマンドラインの指定が優先され、NODE_OPTIONS=--max-old-space-size=1024 node --max-old-space-size=256 では 448 でした。
値はマシンのメモリーより小さくします。公式ドキュメントには「2 GiB のメモリーのマシンなら、ほかの用途のメモリーを残してスワップを避けるため、1536(1.5 GiB)にすることを考えてください」とあります。使えるメモリーに対する割合で決める --max-old-space-size-percentage もあり、Node.js 24.22.1 で --max-old-space-size-percentage=25 を付けると、heap_size_limit は 3610 になりました。
上限を上げても、データが増えれば、上げた上限にもいずれ届きます。扱うデータの量がこの先も増えるなら、1行ずつ読むなど、全件をメモリーに持たない書き方に直すほうが確実です。





