Increasing JavaScript Heap Memory Limit in a Docker Container

Node.js applications have a default heap memory limit, which helps optimize memory usage. However, for applications handling large data sets or under heavy load, this limit might be insufficient, leading to “JavaScript heap out of memory” errors. In this article, I’ll guide you through increasing the heap memory limit in a Docker container by adjusting the max-old-space-size setting.

Problem Definition

You might encounter the following error message in your current Node.js application:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

This error indicates that Node.js has reached its default heap memory limit and cannot allocate more memory. To resolve this, we can increase the max-old-space-size value using the NODE_OPTIONS environment variable.

Checking “Out of Memory” Errors

First, check whether the kernel killed the process or V8 hit its own heap limit. Those are different limits. You can do this by checking the system logs for OOM errors.

1. Access Your Server : Connect to your server via SSH or directly through your terminal.
2. Check System Logs : Use the following command to search for OOM errors in your system logs:

sudo grep -i 'out of memory' /var/log/syslog

Solution: Increasing the Heap Memory Limit

Step 1: Check Current Memory Usage

First, let’s check the current heap memory limit used by your Docker container:

1. Access your Docker container:

docker exec -it n8n /bin/sh

1. Start the Node.js console:

node

1. Check the current max-old-space-size value:

console.log(require('node:v8').getHeapStatistics().heap_size_limit);

Step 2: Stop the Existing Container

Back up the n8n data and record the existing image, mounts, environment, and network settings. Stop the old container and keep it available for rollback:

docker stop n8n
docker rename n8n n8n-before-heap-change

Step 3: Restart the Container with Increased Memory Limit

Recreate the container with its existing settings and set NODE_OPTIONS to a 2048 MiB old-space limit. This example reuses the old container’s volumes. Replace the image and options with those from your deployment:

docker run -d --name n8n -p 5678:5678 \
  --volumes-from n8n-before-heap-change \
  -e NODE_OPTIONS="--max-old-space-size=2048" \
  docker.n8n.io/n8nio/n8n:YOUR_VERSION

Using Docker Compose

If you are using Docker Compose, add the NODE_OPTIONS environment variable to your docker-compose.yml file:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - NODE_OPTIONS=--max-old-space-size=2048

Then restart the container using Docker Compose:

docker compose up -d --force-recreate n8n

Verify the Changes

After making these changes, you should verify that the new memory limit is applied correctly:

1. Access your Docker container again:

docker exec -it n8n /bin/sh

1. Start the Node.js console:

node

1. Check the new max-old-space-size value:

console.log(require('node:v8').getHeapStatistics().heap_size_limit);

heap_size_limit reports V8’s total heap ceiling, which can differ from the old-space limit. Leave room for memory outside the V8 heap, including native buffers, and check the container’s memory limit before increasing it.

Conclusion

By adjusting the max-old-space-size setting, you can increase the heap memory limit for your Node.js application running in a Docker container. This helps prevent memory allocation errors and ensures your application runs smoothly, even under heavy load or with large data sets. If you have any further questions or encounter any issues, feel free to leave a comment below. Happy coding!