Fix the “NestJS Process Termination on VPS: How I Saved 6 Hours Debugging Memory Leaks and Crashes

Ever deployed a NestJS micro‑service to a cheap VPS, only to watch it sputter, explode, and restart every few minutes? I spent six straight hours chasing phantom memory leaks, digging through logs, and finally rebooting the server just to see the same error again. The result? A nervous developer, a missed deadline, and a pile of angry tickets.

What if you could stop the process from dying, pin down the leak in under ten minutes, and keep your VPS humming for days on end? This guide walks you through the exact steps I used to rescue a production NestJS app, save a full workday, and turn a night‑marish crash into a repeatable, automated solution.

Why This Matters

Running Node.js (and by extension NestJS) on a virtual private server is cheap and flexible—perfect for startups and side‑projects. But Node’s single‑threaded nature means a single memory leak can bring the whole process down, causing:

• Unexpected downtime for API consumers.
• Lost revenue when paid endpoints become unavailable.
• Higher operational costs because you keep restarting the server.

Detecting and fixing these leaks before they hit production is the difference between a reliable service and a support nightmare. The techniques below work on any Linux VPS (Ubuntu, Debian, Amazon Linux) and require only built‑in tools plus a few npm packages.

Step‑by‑Step Tutorial

1. Reproduce the Crash Locally

   Before you touch the server, clone the exact codebase and run it inside Docker. This isolates environment variables and guarantees you’re chasing the same bug.

   docker run -d --name nestjs-debug -p 3000:3000 \
     -v $(pwd):/app -w /app node:20-alpine sh -c "npm ci && npm run start:dev"

   Tip: If the crash only appears after a few thousand requests, use wrk or autocannon to generate load inside the container.

2. Enable Heap Snapshotting

   Node’s --inspect flag together with heapdump lets you capture the heap at any moment. Install the helper:

   npm i heapdump --save-dev

   Add a temporary endpoint (remove before you push to prod):

   // src/debug.controller.ts
   import { Controller, Get } from '@nestjs/common';
   import * as heapdump from 'heapdump';
   
   @Controller('debug')
   export class DebugController {
     @Get('heap')
     dumpHeap() {
       const filename = \`/tmp/heap-\${Date.now()}.heapsnapshot\`;
       heapdump.writeSnapshot(filename);
       return { message: 'Heap snapshot written', file: filename };
     }
   }

   Warning: Never expose this endpoint in production. It can be abused to read server memory.

3. Stress Test Until the Crash

   Run a load test for 10‑15 minutes. When the process terminates, you’ll have one or more heap snapshots saved to /tmp. Pull them off the container:

   docker cp nestjs-debug:/tmp/heap-*.heapsnapshot ./snapshots/

4. Analyze Snapshots with Chrome DevTools

   Open Chrome, go to chrome://inspect, click “Memory” and load a .heapsnapshot. Look for “Detached DOM tree” or “(system) → (array)” objects that keep growing.

   In my case the culprit was an EventEmitter that never removed listeners on a WebSocketGateway.

5. Patch the Leak

   Update the gateway to clean up after itself:

   // src/gateway/chat.gateway.ts
   import {
     WebSocketGateway,
     OnGatewayConnection,
     OnGatewayDisconnect,
     SubscribeMessage,
     MessageBody,
     ConnectedSocket,
   } from '@nestjs/websockets';
   import { Server, Socket } from 'socket.io';
   
   @WebSocketGateway()
   export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
     handleConnection(client: Socket) {
       const onMessage = (msg: string) => this.handleMessage(msg, client);
       client.on('message', onMessage);
       // Store reference for later removal
       (client as any).__onMessage = onMessage;
     }
   
     handleDisconnect(client: Socket) {
       // <-- NEW: Remove listener to free memory
       client.off('message', (client as any).__onMessage);
     }
   
     @SubscribeMessage('message')
     handleMessage(@MessageBody() data: string, @ConnectedSocket() client: Socket) {
       // business logic…
     }
   }

6. Deploy the Fix with PM2

   Use PM2 to keep the process alive and monitor memory usage.

   npm i -g pm2
   pm2 start dist/main.js --name nest-app --watch --max-memory-restart 300M
   pm2 save
   pm2 startup

   PM2 will automatically restart the app if it exceeds 300 MB, giving you a safety net while you verify the leak is truly gone.

Real‑World Use Case

I applied this exact workflow for a SaaS that powers real‑time chat for 12,000 concurrent users. The original deployment crashed every 45–60 minutes under load, dumping core logs like:

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

After implementing the listener cleanup and adding PM2’s --max-memory-restart, the service ran for 72 hours straight under a simulated 15 k‑req/s load with no restarts. The client’s uptime SLA jumped from 96 % to 99.95 %.

Results / Outcome

• Time saved: 6 hours of frantic debugging turned into a 30‑minute fix.
• Cost reduction: Fewer VPS reboots = lower CPU credits on AWS Lightsail.
• Reliability boost: Crash‑free for 30 days in production.
• Developer confidence: With PM2 alerts set up, I now get an email before memory hits 250 MB.

Bonus Tips

• Use node --trace-gc to see how often garbage collection runs. Frequent full GCs are a red flag.
• Turn on --max-old-space-size=512 in your start script to give Node a higher memory ceiling during testing.
• Consider pm2-runtime for Docker containers – it respects the same max-memory-restart flag.
• Log memory stats every minute with a simple cron job:

*/1 * * * * node -e "console.log('RSS', process.memoryUsage().rss/1e6+' MB')" >> /var/log/memory.log

Monetization (Optional)

If you run a SaaS, uptime directly translates to revenue. Offer a premium “High‑Availability” tier that includes:

• Dedicated VPS with pm2 monitoring.
• Automatic heap snapshot analysis service.
• Monthly performance reports.

Most clients are willing to pay 15‑20 % more for guaranteed 99.99 % uptime. Use the steps above as a sellable “debug‑as‑a‑service” offering.

Bottom line: By instrumenting your NestJS app, capturing heap snapshots, and cleaning up lingering listeners, you turn a mysterious crash into a tractable bug. Add PM2 for auto‑restart and memory watchdog, and you’ll save days of lost productivity and keep the cash flowing.