From ae315f7b78a7ddef2bbc9fbe9be847f0342ff12b Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sat, 14 Nov 2026 15:33:20 +0000 Subject: [PATCH] src: warn when heap would exceed pointer compression limit In builds without pointer compression, emit a process warning with the code HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT when the heap that survives a full garbage collection suggests that it would not fit in the 4 GiB cage that limits the heap of each isolate when pointer compression is enabled. Pointer compression shrinks a heap by at most half, and by about 40% in practice, so the warning says the heap is likely to exceed the limit from 6.5 GiB, and that it will exceed the limit from 8 GiB. The check runs in a GC epilogue callback for mark-compact GCs only, is done at most once per Environment, and unregisters itself after the warning has been scheduled. The warning can be silenced with --disable-warning=HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT. Assisted-by: Claude Signed-off-by: James M Snell --- doc/api/process.md | 26 ++++ src/env-inl.h | 6 + src/env.cc | 79 +++++++++++ src/env.h | 35 +++++ src/node.cc | 3 + src/node_v8.cc | 21 +++ .../test-heap-pointer-compression-warning.js | 134 ++++++++++++++++++ 7 files changed, 304 insertions(+) create mode 100644 test/parallel/test-heap-pointer-compression-warning.js diff --git a/doc/api/process.md b/doc/api/process.md index d47983a97b4e..2bcac6597665 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -598,6 +598,32 @@ A few of the warning types that are most common include: that will be ignored rather than treated as an error. One example is use of the HTTP response status message when using the HTTP/2 compatibility API. +#### Heap size and pointer compression + + + +When Node.js is built with V8 pointer compression enabled, the V8 heap of each +thread (the main thread and every [`Worker`][]) is limited to 4 GiB, regardless +of `--max-old-space-size`. Pointer compression reduces heap usage, typically by +about 40% and never by more than half, so a heap that is larger than 4 GiB +without pointer compression may or may not fit under that limit. + +In builds without pointer compression, Node.js emits a warning with the code +`'HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT'` when the heap of a thread that +survives a full garbage collection reaches: + +* 6.5 GiB: the heap is likely to exceed the limit with pointer compression. +* 8 GiB: the heap will exceed the limit with pointer compression. + +The warning is emitted at most once per thread, with the wording that matches +the heap size at the time. Memory outside the V8 heap, such as the contents of +{ArrayBuffer}s and {Buffer}s, does not count toward the limit. + +The warning can be silenced with +`--disable-warning=HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT`. + ### Event: `'worker'`