Skip Navigation
Heroku Dev Center Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
Heroku Dev Center Dev Center
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
  • Log in or Sign up
Show nav
View categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Buildpacks
    • Platform Principles
  • Developer Tools
    • AI Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • .NET
      • Working with .NET
    • Clojure
    • Front-end
    • Go
      • Go Dependency Management
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • Node.js
      • Working with Node.js
      • Troubleshooting Node.js Apps
      • Node.js Behavior in Heroku
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Ruby
      • Rails Support
        • Working with Rails
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Scala
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Heroku Postgres Advanced
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Inference Essentials
    • Inference API
    • Inference Quick Start Guides
    • AI Models
    • Tool Use
    • AI Integrations
    • Vector Database
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
    • Heroku AppLink
      • Getting Started with Heroku AppLink
      • Working with Heroku AppLink
      • Heroku AppLink Reference
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Other Salesforce Integrations
  • Language Support
  • Node.js
  • Troubleshooting Node.js Apps
  • Troubleshooting Node.js Memory Use

Troubleshooting Node.js Memory Use

English — 日本語に切り替える

Table of Contents [expand]

  • How Node.js uses memory
  • Heroku memory limits
  • Tuning the garbage collector
  • Running multiple processes
  • Before you debug
  • Monitoring and diagnosing memory usage

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:
    • Cedar – the dyno starts swapping memory to disk and R14 errors appear in your logs. If memory usage keeps growing, the dyno is restarted with an R15 error.
    • Fir – the dyno restarts when memory usage reaches 100% of its quota.

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, or pnpm-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, or pnpm 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 cnb stack.
  • 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.

  1. Start your app locally with the --inspect flag to enable the inspector. For example, node --inspect server.js.
  2. In Chrome, open chrome://inspect and click inspect under your app.
  3. In the Memory tab, take a heap snapshot. This is your baseline.
  4. Send traffic to your app (see Generating load), then take another snapshot. Repeat at least once more.
  5. Select the latest snapshot and change the view from Summary to Comparison, comparing against the baseline. Sort by # Delta or Size Delta.
  6. 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.

Feedback

Log in to submit feedback.

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2026 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices