src: do not enable wasm trap handler if there's not enough vmem by joyeecheung · Pull Request #62132 · nodejs/node

joyeecheung · 2026-03-06T14:50:58Z

The first commit is a backport of https://chromium-review.googlesource.com/c/v8/v8/+/7638233

This complements --disable-wasm-trap-handler and allows users to keep wasm functional in an environment with virtual memory restrictions (e.g. in the case of VS code server run for remote access, the user does not necessary always have the permission on the server to configure NODE_OPTIONS or --disable-wasm-trap-handler - in fact they don't even necessarily know this has anything to do with WASM on Node.js since they shouldn't be aware of what VS code server is implemented with).

Supersedes #60788 - this keeps the estimation logic in Node.js instead, and also keeps it in POSIX because on other systems the issue that this is solving is not practical (e.g. on Windows, one cannot bound the virtual memory available without bounding the physical memory, and it does not make a difference whether trap based bound checks are enabled or not when physical memory limit is reached)

When the amount of virtual memory available does not allow more than 1 wasm cage at startup, Node.js automatically disables trap-based bound checks for wasm - in this case, no wasm can run at all if we keep the trap-based bound checks, so there's no point enabling the optimization. This should remove a good enough of reproductions of Out of memory: Cannot allocate Wasm memory for new instance (after update from 1.100.3 to 1.101) microsoft/vscode#251777 (which is triggered by the usage of wasm in undici)
When the amount of virtual memory allows more than 1 cage, but still less than the usual 128TB on 64-bit systems, the optimization is still optimistically enabled. In this case some initial wasm cage may be allocated but may fail later when there's not enough virtual memory left. This maintains the current behavior when we unconditionally enable the optimzation.
--disable-wasm-trap-handler is kept as an escape hatch for 2.

We can tweak the threshold of estimation of needed wasm cages in 1 in Node.js to reduce the possibility of 2, this PR currently sets the threshold to 1, since even within Node.js core there's already undici that would use one cage whenever fetch() i sused.

Refs: microsoft/vscode#251777
Refs: https://chromium-review.googlesource.com/c/v8/v8/+/7638233

nodejs-github-bot · 2026-03-06T14:51:05Z

Review requested:

@nodejs/gyp
@nodejs/security-wg
@nodejs/startup
@nodejs/v8-update

codecov · 2026-03-06T17:31:34Z

Codecov Report

❌ Patch coverage is 94.44444% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 89.67%. Comparing base (0d7e4b1) to head (322e31d).
⚠️ Report is 69 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node.cc	94.44%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62132      +/-   ##
==========================================
- Coverage   89.68%   89.67%   -0.02%     
==========================================
  Files         676      676              
  Lines      206738   206755      +17     
  Branches    39594    39601       +7     
==========================================
- Hits       185414   185407       -7     
- Misses      13467    13497      +30     
+ Partials     7857     7851       -6

Files with missing lines	Coverage Δ
src/debug_utils.h	`80.00% <ø> (ø)`
src/node.cc	`76.78% <94.44%> (+0.39%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

When the system does not have enough virtual memory for the wasm cage, installing the trap handler would cause any code allocating wasm memory to throw. Therefore it's useful for the embedder to know when the system doesn't have enough virtual address space to allocate enough wasm cages and in that case, skip the trap handler installation so that wasm code can at least work (even not at the maximal performance). Node.js previously has a command line option --disable-wasm-trap-handler to fully disable trap-based bound checks, this new API would allow it to adapt automatically while keeping the optimization in the happy path, since it's not always possible for end users to opt-into disabling trap-based bound checks (for example, when a VS Code Server is loaded in a remote server for debugging). Refs: nodejs/node#62132 Refs: microsoft/vscode#251777 Change-Id: I345c076af2b2b47700e5716b49c3133fdf8a0981 Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-by: Jakob Kummerow <jkummerow@chromium.org> Reviewed-by: Michael Lippautz <mlippautz@chromium.org> Commit-Queue: Joyee Cheung <joyee@igalia.com> Reviewed-by: Clemens Backes <clemensb@chromium.org> Cr-Commit-Position: refs/heads/main@{#105702}

Original commit message: [api] Add V8::GetWasmMemoryReservationSizeInBytes() When the system does not have enough virtual memory for the wasm cage, installing the trap handler would cause any code allocating wasm memory to throw. Therefore it's useful for the embedder to know when the system doesn't have enough virtual address space to allocate enough wasm cages and in that case, skip the trap handler installation so that wasm code can at least work (even not at the maximal performance). Node.js previously has a command line option --disable-wasm-trap-handler to fully disable trap-based bound checks, this new API would allow it to adapt automatically while keeping the optimization in the happy path, since it's not always possible for end users to opt-into disabling trap-based bound checks (for example, when a VS Code Server is loaded in a remote server for debugging). Refs: nodejs#62132 Refs: microsoft/vscode#251777 Change-Id: I345c076af2b2b47700e5716b49c3133fdf8a0981 Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-by: Jakob Kummerow <jkummerow@chromium.org> Reviewed-by: Michael Lippautz <mlippautz@chromium.org> Commit-Queue: Joyee Cheung <joyee@igalia.com> Reviewed-by: Clemens Backes <clemensb@chromium.org> Cr-Commit-Position: refs/heads/main@{#105702} Refs: v8/v8@bef0d9c Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>

nodejs-github-bot · 2026-03-11T00:23:30Z

CI: https://ci.nodejs.org/job/node-test-pull-request/71683/

nodejs-github-bot · 2026-03-11T15:49:35Z

CI: https://ci.nodejs.org/job/node-test-pull-request/71695/

joyeecheung · 2026-03-12T02:32:37Z

cc @nodejs/cpp-reviewers @nodejs/v8 PTAL, this should address microsoft/vscode#251777 (there are also a bunch of similarly confused users on the Internet affected by this issue, like https://www.reddit.com/r/vscode/comments/1ld6fp7/downloading_vs_code_server_loop_when_connecting/ and https://stackoverflow.com/questions/65055955/vscode-ssh-extension-stuck-on-the-installation-step)

Aditi-1400 · 2026-03-12T06:49:58Z

Also, we should update --disable-wasm-trap-handler documentation in cli.md

Original commit message: [api] Add V8::GetWasmMemoryReservationSizeInBytes() When the system does not have enough virtual memory for the wasm cage, installing the trap handler would cause any code allocating wasm memory to throw. Therefore it's useful for the embedder to know when the system doesn't have enough virtual address space to allocate enough wasm cages and in that case, skip the trap handler installation so that wasm code can at least work (even not at the maximal performance). Node.js previously has a command line option --disable-wasm-trap-handler to fully disable trap-based bound checks, this new API would allow it to adapt automatically while keeping the optimization in the happy path, since it's not always possible for end users to opt-into disabling trap-based bound checks (for example, when a VS Code Server is loaded in a remote server for debugging). Refs: nodejs#62132 Refs: microsoft/vscode#251777 Change-Id: I345c076af2b2b47700e5716b49c3133fdf8a0981 Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-by: Jakob Kummerow <jkummerow@chromium.org> Reviewed-by: Michael Lippautz <mlippautz@chromium.org> Commit-Queue: Joyee Cheung <joyee@igalia.com> Reviewed-by: Clemens Backes <clemensb@chromium.org> Cr-Commit-Position: refs/heads/main@{#105702} Refs: v8/v8@bef0d9c Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>

joyeecheung · 2026-03-12T16:06:39Z

@Aditi-1400 Updated the docs, can you take another look? Thanks

src/node.cc

test/wasm-allocation/wasm-allocation.status

nodejs-github-bot · 2026-03-30T15:24:26Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72302/

nodejs-github-bot · 2026-03-31T11:34:09Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72339/

nodejs-github-bot · 2026-03-31T14:28:16Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72346/

nodejs-github-bot · 2026-03-31T20:03:10Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72364/

nodejs-github-bot · 2026-03-31T22:56:28Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72373/

nodejs-github-bot · 2026-04-01T01:18:40Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72375/

nodejs-github-bot · 2026-04-01T11:38:53Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72382/

nodejs-github-bot · 2026-04-01T14:56:28Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72389/

nodejs-github-bot · 2026-04-01T17:37:21Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72396/

nodejs-github-bot · 2026-04-01T19:29:18Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72397/

nodejs-github-bot · 2026-04-01T20:50:11Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72400/

nodejs-github-bot · 2026-04-01T21:47:32Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72401/

nodejs-github-bot · 2026-04-02T10:31:02Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72412/

nodejs-github-bot · 2026-04-02T13:09:52Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72422/

nodejs-github-bot · 2026-04-02T19:25:41Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72434/

nodejs-github-bot · 2026-04-02T22:41:32Z

Landed in 5ff1eab...b411f90

Original commit message: [api] Add V8::GetWasmMemoryReservationSizeInBytes() When the system does not have enough virtual memory for the wasm cage, installing the trap handler would cause any code allocating wasm memory to throw. Therefore it's useful for the embedder to know when the system doesn't have enough virtual address space to allocate enough wasm cages and in that case, skip the trap handler installation so that wasm code can at least work (even not at the maximal performance). Node.js previously has a command line option --disable-wasm-trap-handler to fully disable trap-based bound checks, this new API would allow it to adapt automatically while keeping the optimization in the happy path, since it's not always possible for end users to opt-into disabling trap-based bound checks (for example, when a VS Code Server is loaded in a remote server for debugging). Refs: #62132 Refs: microsoft/vscode#251777 Change-Id: I345c076af2b2b47700e5716b49c3133fdf8a0981 Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-by: Jakob Kummerow <jkummerow@chromium.org> Reviewed-by: Michael Lippautz <mlippautz@chromium.org> Commit-Queue: Joyee Cheung <joyee@igalia.com> Reviewed-by: Clemens Backes <clemensb@chromium.org> Cr-Commit-Position: refs/heads/main@{#105702} Refs: v8/v8@bef0d9c Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com> PR-URL: #62132 Refs: microsoft/vscode#251777 Refs: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-By: Aditi Singh <aditisingh1400@gmail.com>

PR-URL: #62132 Refs: microsoft/vscode#251777 Refs: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-By: Aditi Singh <aditisingh1400@gmail.com>

Original commit message: [api] Add V8::GetWasmMemoryReservationSizeInBytes() When the system does not have enough virtual memory for the wasm cage, installing the trap handler would cause any code allocating wasm memory to throw. Therefore it's useful for the embedder to know when the system doesn't have enough virtual address space to allocate enough wasm cages and in that case, skip the trap handler installation so that wasm code can at least work (even not at the maximal performance). Node.js previously has a command line option --disable-wasm-trap-handler to fully disable trap-based bound checks, this new API would allow it to adapt automatically while keeping the optimization in the happy path, since it's not always possible for end users to opt-into disabling trap-based bound checks (for example, when a VS Code Server is loaded in a remote server for debugging). Refs: nodejs#62132 Refs: microsoft/vscode#251777 Change-Id: I345c076af2b2b47700e5716b49c3133fdf8a0981 Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-by: Jakob Kummerow <jkummerow@chromium.org> Reviewed-by: Michael Lippautz <mlippautz@chromium.org> Commit-Queue: Joyee Cheung <joyee@igalia.com> Reviewed-by: Clemens Backes <clemensb@chromium.org> Cr-Commit-Position: refs/heads/main@{#105702} Refs: v8/v8@bef0d9c Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com> PR-URL: nodejs#62132 Refs: microsoft/vscode#251777 Refs: https://chromium-review.googlesource.com/c/v8/v8/+/7638233 Reviewed-By: Aditi Singh <aditisingh1400@gmail.com>

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Mar 6, 2026

joyeecheung marked this pull request as draft March 6, 2026 14:51

joyeecheung mentioned this pull request Mar 6, 2026

[WIP] only install WASM trap handler when there's enough virtual memory #60788

Closed

joyeecheung force-pushed the wasm-handler-2 branch from 0c431d9 to 831617f Compare March 10, 2026 20:55

This comment was marked as outdated.

Sign in to view

joyeecheung force-pushed the wasm-handler-2 branch 2 times, most recently from de51d96 to 37b5c46 Compare March 11, 2026 00:22

joyeecheung marked this pull request as ready for review March 12, 2026 02:27

joyeecheung changed the title ~~[WIP] src: do not enable wasm trap handler if there's not enough vmem~~ src: do not enable wasm trap handler if there's not enough vmem Mar 12, 2026

joyeecheung added the review wanted PRs that need reviews. label Mar 12, 2026

joyeecheung added wasm Issues and PRs related to WebAssembly. memory Issues and PRs related to the memory management or memory footprint. lts-watch-v22.x PRs that may need to be released in v22.x lts-watch-v24.x PRs that may need to be released in v24.x labels Mar 12, 2026

joyeecheung force-pushed the wasm-handler-2 branch from 37b5c46 to f61ab3b Compare March 12, 2026 16:06

joyeecheung force-pushed the wasm-handler-2 branch 2 times, most recently from bab88bb to 6219aca Compare March 12, 2026 17:32

sxa mentioned this pull request Mar 13, 2026

Tracking issue for problems on RISC-V Linux platform nodejs/build#4099

Open

10 tasks

Aditi-1400 reviewed Mar 16, 2026

View reviewed changes

src/node.cc Outdated Show resolved Hide resolved

test/wasm-allocation/wasm-allocation.status Outdated Show resolved Hide resolved

Aditi-1400 approved these changes Mar 30, 2026

View reviewed changes

joyeecheung added the request-ci Add this label to start a Jenkins CI on a PR. label Mar 30, 2026

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Mar 30, 2026

joyeecheung added request-ci Add this label to start a Jenkins CI on a PR. and removed request-ci Add this label to start a Jenkins CI on a PR. labels Apr 1, 2026

joyeecheung added the request-ci Add this label to start a Jenkins CI on a PR. label Apr 2, 2026

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Apr 2, 2026

joyeecheung added commit-queue Add this label to land a pull request using GitHub Actions. commit-queue-rebase Add this label to allow the Commit Queue to land a PR in several commits. labels Apr 2, 2026

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 2, 2026

nodejs-github-bot closed this Apr 2, 2026

Uh oh!

Conversation

joyeecheung commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Mar 6, 2026

Uh oh!

codecov bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as outdated.

nodejs-github-bot commented Mar 11, 2026

Uh oh!

nodejs-github-bot commented Mar 11, 2026

Uh oh!

joyeecheung commented Mar 12, 2026

Uh oh!

Aditi-1400 commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joyeecheung commented Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

nodejs-github-bot commented Mar 30, 2026

Uh oh!

nodejs-github-bot commented Mar 31, 2026

Uh oh!

nodejs-github-bot commented Mar 31, 2026

Uh oh!

nodejs-github-bot commented Mar 31, 2026

Uh oh!

nodejs-github-bot commented Mar 31, 2026

Uh oh!

nodejs-github-bot commented Apr 1, 2026

Uh oh!

nodejs-github-bot commented Apr 1, 2026

Uh oh!

nodejs-github-bot commented Apr 1, 2026

Uh oh!

nodejs-github-bot commented Apr 1, 2026

Uh oh!

nodejs-github-bot commented Apr 1, 2026

Uh oh!

nodejs-github-bot commented Apr 1, 2026

Uh oh!

nodejs-github-bot commented Apr 1, 2026

Uh oh!

nodejs-github-bot commented Apr 2, 2026

Uh oh!

nodejs-github-bot commented Apr 2, 2026

Uh oh!

nodejs-github-bot commented Apr 2, 2026

Uh oh!

nodejs-github-bot commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joyeecheung commented Mar 6, 2026 •

edited

Loading

codecov bot commented Mar 6, 2026 •

edited

Loading

Aditi-1400 commented Mar 12, 2026 •

edited

Loading