Tired of your Next.js app in Docker eating all your RAM? Learn why Node’s garbage collector is the real culprit and discover three practical fixes, from the quick `node-caged` hack to the production-ready `NODE_OPTIONS` environment variable.

Next.js in Docker is Eating Your RAM. Is ‘node-caged’ the Answer?

It was 2 AM on a Tuesday. Of course it was. PagerDuty was screaming about our Kubernetes cluster, specifically the `web-frontend` pods. They were in a constant crash loop, getting OOMKilled (Out Of Memory) by the scheduler. This wasn’t some complex microservice; it was a fairly standard Next.js marketing site we’d just deployed. The resource limits were generous—or so we thought. I remember staring at the Grafana dashboard, watching the memory usage graph for each new pod look like a sheer cliff face. It would start, climb relentlessly, hit the 512MB limit, and poof—gone. My first thought was a memory leak, but after hours of digging, the truth was both simpler and way more infuriating. The problem wasn’t our code; it was Node.js itself being a terrible guest inside a Docker container.

The “Why”: Node.js Doesn’t Read the Room (or the cgroup)

So, what’s actually going on here? You’ve carefully set a memory limit in your Dockerfile or your Kubernetes manifest, say `512m`. You assume Node.js will see that and play nice. Wrong.

By default, the Node.js V8 engine—the part that runs your JavaScript—looks at the host machine’s total memory, not the container’s limit. If your Docker host (like `k8s-worker-node-3b`) has 64GB of RAM, V8 thinks it has a massive playground. It gets lazy with its garbage collection (GC), holding onto memory because it assumes there’s plenty more where that came from. It keeps allocating memory until it smacks headfirst into the container’s hard cgroup limit, and the orchestrator’s kernel OOM killer unceremoniously shoots it in the head. It’s not a leak; it’s just bad manners.

This is why you see that relentless climb. The application isn’t necessarily using all that RAM, but the V8 engine hasn’t been given a reason to clean up after itself yet. The Reddit thread you saw highlights a clever solution, `node-caged`, but it’s just one tool in our belt. Let’s break down the options.

The Fixes: From a Quick Hack to a Permanent Solution

We’ve got a few ways to tackle this, each with its own pros and cons. I tend to think of them in tiers of complexity and “production-readiness.”

Solution 1: The Quick Fix – Using `node-caged`

This is the fix from the Reddit thread, and it’s a smart one. `node-caged` is a wrapper script that inspects the container’s cgroup limits and automatically sets the appropriate V8 flags for you before running your Node process. It does the heavy lifting so you don’t have to.

Your Dockerfile would change from this:

# Before
FROM node:18-alpine
# ... copy files, etc.
CMD ["node", "server.js"]

To this:

# After
FROM ananask/node-caged:18-alpine
# ... copy files, etc.
# The entrypoint is already 'node-caged', so you just provide the command
CMD ["node", "server.js"]

My Take: This is a brilliant and elegant solution for dev environments or small projects. It’s “automagic” and works without extra configuration. However, at TechResolve, we’re a bit hesitant to introduce another third-party wrapper into the base image of our critical production services. It’s another dependency to track and trust.

Solution 2: The Production-Ready Fix – `NODE_OPTIONS`

This is my preferred method and what we use for all our Node.js services. Instead of relying on a wrapper, we can explicitly tell the V8 engine how much memory it’s allowed to use via an environment variable. The magic flag is --max-old-space-size.

You can set this directly in your Dockerfile. A good rule of thumb is to set it to about 75-80% of your container’s memory limit to leave room for other process overhead.

# Dockerfile for a container with a 512MB limit
FROM node:18-alpine

# ... other setup ...

# Set max heap size to ~400MB
ENV NODE_OPTIONS="--max-old-space-size=400"

WORKDIR /usr/src/app

COPY --from=builder /usr/src/app/package*.json ./
COPY --from=builder /usr/src/app/.next ./.next
COPY --from=builder /usr/src/app/public ./public
COPY --from=builder /usr/src/app/node_modules ./node_modules

EXPOSE 3000

CMD ["node_modules/.bin/next", "start"]

This approach is explicit, uses official Node.js functionality, and doesn’t require a different base image. It makes your resource constraints crystal clear to anyone reading the Dockerfile.

Solution 3: The ‘Defense in Depth’ Fix – Orchestrator Limits

This isn’t a fix for Node’s memory consumption, but rather a way to manage it gracefully. You should always be doing this in addition to one of the fixes above. This is about setting proper resource requests and limits in your orchestration layer (like Kubernetes).

• requests.memory: The amount of memory Kubernetes guarantees for your pod. The scheduler uses this to decide where to place the pod.
• limits.memory: The hard ceiling. If your pod exceeds this, it gets OOMKilled.

Here’s a snippet from a Kubernetes deployment YAML:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nextjs-frontend
spec:
  template:
    spec:
      containers:
      - name: web-app
        image: my-company/nextjs-app:1.2.3
        ports:
        - containerPort: 3000
        env:
        - name: NODE_OPTIONS
          value: "--max-old-space-size=400"
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"

By setting a request lower than the limit, you tell Kubernetes, “Hey, this app usually runs fine at 256MB, but please give it a hard ceiling of 512MB just in case.” This combination ensures stability for the node and predictable behavior for your app. The `NODE_OPTIONS` flag prevents it from ever hitting the limit, and the limit is your safety net if something goes terribly wrong.

Conclusion & Comparison

So, is `node-caged` the answer? It can be. But it’s not the only answer. For me, being explicit is better than being implicit, especially in production.

Ultimately, the late-night incident was solved by implementing Solution 2 and 3 together. We set the `NODE_OPTIONS` in our base Node image and enforced strict `requests` and `limits` in our Helm charts. The memory usage graphs flattened out, PagerDuty went silent, and I finally got some sleep. Don’t let the V8 engine’s greediness catch you off guard.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions