How to debug memory leaks?

[meronogbai]

Summary

How do I go about detecting memory leaks or related issues?

I'm getting 504s due to memory limits and idk how to even start debugging memory issues on vercel. This error is very rare and happens around 1 or 2 times per day.

On a normal node app, I'd take heap snapshots but I don't know how to do so in vercel.

FWIW, I enabled these settings

Additional information

No response

Example

No response

[xabierlameiro]

You can't take a heap snapshot on Vercel, so don't try. Reproduce the process locally instead. A production build running under node on your laptop is the same server that's serving those 504s.

next build   # with output: "standalone"
node --expose-gc .next/standalone/server.js

Then load one route at a time, and sample the heap after a forced GC between rounds. One route at a time is the part people skip. A whole-app load test tells you the number went up, not which handler did it.

Before trusting any of it, plant a leak you know is there. A module-level array you push into on every request will do. Check that your setup catches it. On mine that route reports +472 MB per 1000 requests, which is what a real signal looks like. Without that control a flat line means "my harness is broken" just as often as it means "no leak", and there's no way to tell which. I've lost hours to flat lines that were the first one.

Two things that will mislead you.

Big responses look like leaks. A route of mine measured +603 MB per 1000 requests and I nearly wrote it up. It was the cache holding a 0.5 MB payload per distinct key, doing exactly what it's supposed to. Cutting the response to a couple of rows took it down to +88 MB, and at that size the snapshot was small enough to diff, which is when I could see what was actually growing. Use a trivial response when you're testing the mechanism.

Your symptom doesn't sound like retention. Something that kills a process once or twice a day, rarely, is odd for a leak. Retention is monotonic, so it usually kills you on a schedule. Rare 504s look more like peak pressure: one request allocating far above the others, and you only go over when it lands next to something else. That's a different measurement. Retention is heap after GC across cycles. Peak is the high-water mark inside a single request, and forcing a GC before you sample hides it entirely.

Which is the other thing worth knowing. --expose-gc with a collect before each sample is what everyone reaches for first, and it draws a flat line on several real leaks, because their weight is in arrayBuffers and not the JS heap. Sample rss and arrayBuffers without forcing a collection as well, and compare the two.

I package this as next-leak. Per-route cycles, forced-GC sampling, the peak measurement, and it names the retaining object from snapshot diffs:

npx next-leak .

Node 22+ and output: "standalone". Attribution needs a Turbopack build with server sourcemaps; on webpack you still get the verdicts and raw retainer chains, just not names.

If you post the route and roughly what it allocates per request, I'll tell you what to compare.

[gilangabdian]

A 504 on Vercel does not automatically mean a memory leak.

In the screenshot, the function is hitting both 3009 MB / 3009 MB and 19.30s / 15s, so I would investigate the memory and duration independently first.

For production, start with Vercel Observability → Functions. Vercel exposes function memory metrics and runtime logs, including function memory usage, duration, and the route/function involved. This lets you identify whether one route consistently has unusually high peak memory instead of guessing from occasional 504s.

I would also log sampled process.memoryUsage() values around the suspicious handler:

const m = process.memoryUsage()

console.log({
  rss: Math.round(m.rss / 1024 / 1024),
  heapUsed: Math.round(m.heapUsed / 1024 / 1024),
  heapTotal: Math.round(m.heapTotal / 1024 / 1024),
  external: Math.round(m.external / 1024 / 1024),
  arrayBuffers: Math.round(m.arrayBuffers / 1024 / 1024),
})

The important part is to look at the trend, not one measurement:

• heapUsed keeps growing after GC → possible JS/V8 retention
• rss grows while the JS heap is relatively stable → investigate native/external memory
• arrayBuffers grows → investigate buffers, streams, responses, uploads, etc.
• memory rises during a request and then settles → probably a peak/working-set problem rather than a leak

For actual heap snapshots, I would reproduce the problem locally using the production build, rather than trying to attach the Node inspector to a Vercel Function:

next build
node --expose-gc .next/standalone/server.js

Then load one route at a time, take a baseline snapshot, exercise that route repeatedly, force GC, and take another snapshot. Node provides v8.writeHeapSnapshot() for generating snapshots, which can then be opened in Chrome DevTools. Note that generating a snapshot itself can require roughly twice the heap size and can block the event loop, so I would not use this as a production request handler.

Also, don't just increase the Vercel memory limit and consider the problem solved. More memory can provide headroom, but it does not fix a monotonic leak. Vercel's current guidance is to monitor peak memory in Observability and investigate functions approaching their limit.

For a Next.js-specific automated workflow, next-leak is also worth looking at:

npx next-leak .

It runs routes in a fresh process and compares memory across cycles, which is useful for distinguishing normal allocation from retained memory. It currently targets standalone Next.js builds and Node 22+.

References:

Vercel: Detect memory/OOM failures — https://vercel.com/kb/guide/detect-memory-and-oom-failures-in-serverless-functions
Vercel: Observability — https://vercel.com/docs/observability
Vercel: Runtime Logs — https://vercel.com/docs/logs/runtime
Vercel: Function timeouts — https://vercel.com/docs/errors/FUNCTION_INVOCATION_TIMEOUT
Node.js v8.writeHeapSnapshot() — https://nodejs.org/api/v8.html
next-leak — https://github.com/xabierlameiro/next-leak

[Icyubahiro-Jay-P]

You can't take heap snapshots on Vercel serverless functions, so the practical way is to reproduce the issue locally with a production build. Add output: 'standalone' to your next.config.js, run next build, then start the server with node --expose-gc .next/standalone/server.js. Hit one route at a time, force GC between rounds, and sample memory with process.memoryUsage() looking at rss, heapUsed, heapTotal, external and arrayBuffers. Rare 504s that only happen once or twice a day usually look more like peak pressure on a single request than a classic monotonic leak, so also check Vercel Observability → Functions for the exact route and peak memory. You can further automate the comparison with npx next-leak . which works with standalone output and Node 22+. If you share the route that’s failing I can help narrow it down further.