Last updated November 17, 2026
When your Node.js app uses more memory than its dyno provides, it can slow down, log R14 - Memory quota exceeded errors (on Cedar-generation apps), or be restarted. If the JavaScript heap fills up, the process can also crash with JavaScript heap out of memory, even when the dyno has memory to spare. This article explains how Node.js uses memory, how to size it for your dyno, and how to find and fix memory leaks.
The examples in this article use ES modules. To run them, set "type": "module" in your package.json or use the .mjs file extension.
How Node.js uses memory
Node.js runs on the V8 JavaScript engine. A Node.js process uses memory in several areas:
- The heap – where JavaScript objects live, managed by the garbage collector (GC)
- The stack – function call frames and local primitive values
- External memory – memory held outside the heap, such as
Buffers,ArrayBuffers, and native modules
You can inspect how Node.js is using these memory resources at any time in a running application by calling process.memoryUsage(). For example:
import { memoryUsage } from 'node:process';
console.log(memoryUsage());
// Prints:
// {
// rss: 4935680,
// heapTotal: 1826816,
// heapUsed: 650472,
// external: 49879,
// arrayBuffers: 9386
// }
The rss (Resident Set Size) value is the total memory the process is using. Your dyno’s memory limit applies to the combined rss of all processes running on it.
The heap and garbage collection
V8 divides the heap into two generations:
- New Space – New objects are allocated here. GC runs frequently and quickly.
- Old Space – Objects that survive several New Space collections are moved here. GC runs less often and is more expensive.
The size of Old Space is capped by a heap limit. As Old Space fills up, GC runs more often and takes longer, which slows response times. If the heap reaches its limit, the process crashes with JavaScript heap out of memory.
Memory leaks vs. insufficient memory
- Memory leak – Objects are unintentionally kept reachable, so GC can never reclaim them. Memory used after GC grows steadily over time or with request volume. Increasing memory only delays the crash.
- Insufficient memory – The application legitimately needs more memory than is available. Memory used after GC levels off near the limit. Increasing the heap limit or dyno size resolves it.
Leaks can also occur in external memory (for example, Buffers that are never released). These grow rss without growing the heap, and they won’t appear in heap snapshots.
When memory problems matter
The impact of a memory leak depends on how fast it grows. A leak that adds a small amount of memory on each request can quickly become a problem during a sudden increase in traffic, leading to slow responses, crashes, and dropped requests.
If a leak is small and only happens on a rarely used code path, it may not be worth tracking down. Heroku restarts dynos at least once per day, and whenever you deploy or change config vars, which resets memory usage. These restarts can also hide a slow leak until a change in traffic or deploy frequency exposes it. If you’ve disabled daily dyno restarts on a Fir-generation app, slow leaks have more time to build up.
Heroku memory limits
The memory available to your application depends on your dyno size. Your app can run into two separate limits:
- The Node.js heap limit – if the JavaScript heap fills up, the process crashes with
JavaScript heap out of memory. This can happen even when the dyno still has free memory. See Tuning the garbage collector. - The dyno memory limit – applies to the total memory used by all processes on your dyno (
rss), including memory outside the heap. What happens when you exceed it depends on your app’s generation:
See Dyno Memory Behavior for details.
As your app approaches or exceeds these limits, you may notice:
- Slower response times and higher CPU usage – as the heap fills, the garbage collector runs more often. Application code is paused while garbage collection phases are executing.
- Severe slowdowns when swapping (Cedar) – garbage collection must read swapped-out memory back from disk, which is much slower than RAM.
To track memory usage over time and catch these problems early, see Monitoring and diagnosing memory usage.
Tuning the garbage collector
Node.js sets a default heap limit based on the memory it detects. How well this matches your dyno depends on your app’s generation.
Fir – Node.js detects the dyno’s memory limit. The default maximum Old Space size is about half the dyno’s memory, with a minimum of 256 MiB and a maximum of 2 GiB (4 GiB on dynos with 16 GiB of memory or more):
| Dyno memory | Default Old Space limit (approx.) |
|---|---|
| 0.5 GiB | 256 MiB |
| 1 GiB | 512 MiB |
| 4–8 GiB | 2 GiB |
| 16 GiB or more | 4 GiB |
Cedar – Node.js can’t detect the dyno’s memory limit and instead sizes the heap based on the host machine’s memory. On smaller dynos, this default can be larger than the dyno’s memory, so your app can exceed its memory quota before the garbage collector works to reclaim memory, leading to swapping and R14 errors.
On these dynos, we recommend setting --max-old-space-size to about half of your dyno’s memory, the same ratio Node.js uses when it can detect the memory limit:
| Dyno | Memory | --max-old-space-size |
|---|---|---|
| Eco / Basic / Standard-1X | 512 MiB | 256 |
| Standard-2X / Private-S / Shield-S | 1 GiB | 512 |
On Performance-M, Private-M, Shield-M and larger dynos, a single Node.js process can’t take advantage of the dyno’s CPUs, so we recommend running multiple processes and giving each one a share of the heap. See Optimizing Node.js Application Concurrency for the recommended heap limit on every dyno size.
You can configure this in your Procfile. For example:
web: node --max-old-space-size=256 server.js
If you change dyno size, update this value.
--max-old-space-size only limits Old Space. New Space is sized separately and can add up to 200 MiB more, depending on your Node.js version. Together with memory used outside the heap, such as Buffers, this is why we recommend half of your dyno’s memory rather than more. If your app still exceeds the dyno’s memory, see Heap size flags for limiting New Space with --max-semi-space-size.
Heap size flags
Set heap flags on the command that starts your app in your Procfile, as shown in the example above, so they only apply when your app runs:
--max-old-space-size– the maximum Old Space size, in MiB. See the recommendations above.--max-semi-space-size– the maximum size of each New Space semi-space, in MiB. On Fir dynos with less memory, Node.js may choose a very small default, which causes frequent garbage collection for applications that create many short-lived objects. Increasing it can improve throughput and latency for workloads like React server-side rendering and Next.js. New Space uses about three times this value in memory, so account for it in your dyno’s memory budget. On smaller dynos, you can also lower it (for example,--max-semi-space-size=16) to reduce memory usage. Benchmark your application before and after changing it.
Avoid setting heap flags with the NODE_OPTIONS config var. For Cedar-generation apps and Fir-generation apps with the build time config vars feature on, config vars also apply during the build, so a low heap limit can cause build steps (such as bundling frontend assets) to fail with JavaScript heap out of memory.
Running multiple processes
If you cluster your app to take advantage of extra CPUs, the Node.js processes compete with each other for your dyno’s memory.
Each Node.js process sets its own heap limit as if it had the whole dyno to itself. On most dyno sizes, the default heap limits of all your processes add up to more than the dyno’s memory. To prevent this, give each process a heap limit of half the dyno’s memory divided by the number of processes, up to 4096 MiB. Flags such as --max-old-space-size that you pass to the cluster primary apply to every worker.
See Optimizing Node.js Application Concurrency for the recommended number of processes and heap limit for each dyno size, and an example of clustering your app.
Don’t choose the number of processes based on CPU count alone. The total memory used by all processes must stay within your dyno’s memory limit. On Fir and on Cedar Basic and Standard dynos, os.cpus() and os.availableParallelism() can also report the host machine’s CPUs rather than your dyno’s, so the count can be several times too high.
Before you debug
If memory usage changed suddenly, start by finding what changed around that time. The Metrics tab shows deploys as markers on its charts, so you can see whether an increase in memory usage lines up with a deploy. You can also use heroku releases to see your app’s deploy history.
- Application code – review the code changes in deploys around that time.
- Dependencies – compare your lockfile (
package-lock.json,yarn.lock, orpnpm-lock.yaml) between deploys to see which packages changed. - Node.js version – check the resolved Node.js version in your build logs. If you specify a version range like
26.x, each deploy installs the latest matching release, so the Node.js version can change even if your code didn’t. - Stack – if you recently upgraded your stack, the new stack takes effect on the next deploy.
Memory issues are sometimes caused by bugs in Node.js or your dependencies that have already been fixed. To rule these out, we recommend:
- Running on the latest stack
- Running on the Active LTS version of Node.js
- Keeping dependencies up to date (
npm outdated,yarn outdated, orpnpm outdated)
Monitoring and diagnosing memory usage
Start by watching how your app’s memory changes over time. If memory usage keeps climbing while traffic stays steady, you likely have a memory leak. If it climbs and then levels off near your dyno’s limit, your app needs more memory than it has. Use a larger dyno or run fewer processes.
Monitoring memory on Heroku
- Metrics – the Memory Usage chart shows your dynos’ memory usage against their quota. It isn’t available for Eco dynos. On Fir, swap isn’t reported.
- Log runtime metrics (Cedar) – writes each dyno’s memory usage (
memory_rss,memory_swap,memory_quota) to your logs about every 20 seconds. - Node.js language metrics (Cedar) – adds garbage collection and event loop metrics to the Metrics tab. If time spent in garbage collection rises along with memory usage, the heap is near its limit. It isn’t available for Eco dynos or apps using the
cnbstack. - Heroku Telemetry (Fir) – exports dyno metrics with OpenTelemetry to an observability backend of your choice. Your app can also send its own metrics, such as heap usage, with the OpenTelemetry SDK.
- Monitoring add-ons – third-party tools that can track heap usage, garbage collection, and memory over time.
None of Heroku’s built-in metrics report heap usage. To see it on any dyno, log process.memoryUsage() periodically from your app.
Generating load
Most leaks only show up under traffic. Load testing tools such as autocannon or k6 can send steady requests to your app while you watch its memory or take snapshots:
$ npx autocannon -d 60 http://localhost:3000
To load test an app running on Heroku, see Application Load Testing. Use a separate app rather than production, and review the Load Testing Guidelines to see whether your test needs pre-approval.
Finding a leak with heap snapshots
A heap snapshot records every object on the heap and what keeps it reachable. A single snapshot shows what’s using memory. Comparing snapshots taken over time shows what’s growing.
- Start your app locally with the
--inspectflag to enable the inspector. For example,node --inspect server.js. - In Chrome, open
chrome://inspectand click inspect under your app. - In the Memory tab, take a heap snapshot. This is your baseline.
- Send traffic to your app (see Generating load), then take another snapshot. Repeat at least once more.
- Select the latest snapshot and change the view from Summary to Comparison, comparing against the baseline. Sort by # Delta or Size Delta.
- Objects whose count keeps growing between snapshots are likely leaks. Select one and check the Retainers panel to see the chain of references keeping it in memory. This usually leads to the cause, such as a global array, a cache without a size limit, or an event listener that’s never removed.
Taking a snapshot always starts with garbage collection, so any object that remains is still reachable. Entries in parentheses, such as (compiled code), are V8 internals. Start with your application’s own object types.
For more detail, see Record heap snapshots in the Chrome DevTools docs and Using Heap Snapshot in the Node.js docs.
Taking a heap snapshot on a dyno
Connecting Chrome DevTools to a running dyno is only possible on Cedar, using Heroku Exec. Heroku Exec isn’t supported in Shield Private Spaces, and each connection lasts up to 1 hour. On Fir, use the monitoring tools above and reproduce the leak locally to take snapshots.
Creating a heap snapshot blocks your app’s event loop and needs about twice the heap’s size in memory. On a dyno that’s already near its memory limit, this can cause R14 and R15 errors. Use a separate staging app rather than production.
Add --inspect to the command that starts your app in your Procfile:
web: node --inspect=9090 server.js
Deploy the change, then forward the port to your machine:
$ heroku ps:forward 9090
Listening on 9090 and forwarding to web.1:9090...
In Chrome, open chrome://inspect, click Configure, add localhost:9090, then click inspect under your app. Follow the steps in Finding a leak with heap snapshots.
Anyone who can connect to the inspector can run code in your app. Don’t bind it to a public interface (for example, --inspect=0.0.0.0:9090). Remove the flag when you’re done.