Increase min_semi_space_size when possible to make v8 default heap space sizes less catastrophic for containers and memory-constrained environments

[jedwards1211]

What is the problem this feature will solve?

Since upgrading from Node 20 to 24, I've been struggling to figure out why our production app memory usage slowly increases, but then the app starts becoming responsive instead of running OOM.

@mcollina I just ran into your article on Node.js heap tuning which mentions the following, and explains a lot about what I've been seeing. But ARGH why wasn't this in the release notes for Node 22??? This was crucial to warn people about so they don't get shafted!

An essential nuance in V8's memory management emerged around the Node.js v22 release cycle concerning how the default size for the New Space semi-spaces is determined. Unlike some earlier versions with more static defaults, newer V8 versions incorporate heuristics that attempt to set this default size dynamically, often based on the total amount of memory perceived as available to the Node.js process when it starts. This is highly relevant for applications deployed in containers (like Docker on Kubernetes) or serverless platforms (like AWS Lambda or Google Cloud Functions) where memory limits are often set relatively low (e.g., 512MB, 1GB, 2GB). In such scenarios, V8's dynamic calculation might result in an unexpectedly small default --max-semi-space-size, sometimes as low as 1 MB or 8 MB.

... Therefore, for applications running on Node.js v22 or later within memory-limited contexts, relying solely on the default V8 settings for semi-space size is generally discouraged. Developers should strongly consider profiling their application and explicitly setting the --max-semi-space-size flag

What is the feature you are proposing to solve the problem?

In such scenarios, V8's dynamic calculation might result in an unexpectedly small default --max-semi-space-size, sometimes as low as 1 MB or 8 MB.

Prevent this from happening by passing a default min_semi_space_size to V8 with a high enough value that the auto semi space size doesn't go below what older versions of Node used, unless the user overrides it or other constraints given by the user/detected available memory are so low that would be unreasonable.

What alternatives have you considered?

This is making me question whether I can trust Node.js maintenance to be predictable going forward.

[jedwards1211]

According to the docs the default semi space would be just 1MiB for a 64-bit system with 512MB of available memory. That seems absurdly low. What kind of workload could this possibly make sense for?

I don't think abiding by all of V8's defaults makes sense, because their main goal is probably supporting browsers on a variety of devices, rather than supporting servers

[jedwards1211]

Actually I guess the semi space size is dynamic and the min/max parameters are just bounds, so the max is what should be increased, like other people have been saying. I guess I will close this as a duplicate of nodejs/performance#67

[joebowbeer]

@jedwards1211 I agree that this should have been called out in release notes.

I was able to update the docs:

The default value depends on the memory limit. For example, on 64-bit systems with a memory limit of 512 MiB, the max size of a semi-space defaults to 1 MiB. For memory limits up to and including 2GiB, the default max size of a semi-space will be less than 16 MiB on 64-bit systems.

Which is accurate, at least, but not prescriptive!

Is an additional paragraph of guidance needed for developers who are running NodeJS on pods with memory limits of 2Gi or less?

[jedwards1211]

To me the main problem is that there's never been any obvious guidance like "better learn about GC tuning before you deploy a Node.js app to production". And awareness of this is further diminished by the fact that anyone deploying to lambdas or Vercel or similar serverless environments probably doesn't have to worry about GC tuning.

Matteo's article was a big help but if tuning the semi space is so crucial for a real deployment, it belongs in a getting started guide honestly.