Node.js Memory Leak Detector

Diagnose and fix Node.js memory leaks using heap snapshots, clinic.js, and process.memoryUsage(). Covers the most common leak patterns and production monitoring strategies.

Quick Memory Health Check

// memory-monitor.ts — add to any Node.js app
function logMemory(label = '') {
  const m = process.memoryUsage();
  console.log(`[Memory${label ? ' ' + label : ''}]`, {
    heapUsed:  `${(m.heapUsed  / 1024 / 1024).toFixed(1)} MB`,
    heapTotal: `${(m.heapTotal / 1024 / 1024).toFixed(1)} MB`,
    rss:       `${(m.rss       / 1024 / 1024).toFixed(1)} MB`,
    external:  `${(m.external  / 1024 / 1024).toFixed(1)} MB`,
  });
}

// Log every 60 seconds — if heapUsed grows continuously: leak suspected
setInterval(() => logMemory('60s'), 60_000).unref();

// Or use with load test:
logMemory('before');
await runLoadTest();
global.gc?.();  // force GC (start with --expose-gc flag)
logMemory('after');

Heap Snapshot with Chrome DevTools

# 1. Start app with inspector
node --inspect server.js
# or attach inspector to running process:
node --inspect=0.0.0.0:9229 server.js

# 2. Open Chrome → chrome://inspect → click your target
# 3. Memory tab → Heap snapshot → Take snapshot (before)
# 4. Perform the leaking action 10-20 times
# 5. Take snapshot (after)
# 6. Switch dropdown to "Comparison" mode
# 7. Sort by "# Delta" — growing object counts indicate the leak

// Programmatic heap snapshot (useful in staging)
const v8 = require('v8');
const path = require('path');

function takeHeapSnapshot() {
  const filename = `heap-${Date.now()}.heapsnapshot`;
  const fullPath = v8.writeHeapSnapshot(path.join('/tmp', filename));
  console.log(`Heap snapshot written to: ${fullPath}`);
  return fullPath;
}

// Trigger on SIGUSR2 (kill -USR2 <pid>)
process.on('SIGUSR2', () => takeHeapSnapshot());

clinic.js — Automated Diagnosis

# Install clinic.js
npm install -g clinic autocannon

# 1. Run Doctor (auto-diagnoses memory, CPU, event loop)
clinic doctor -- node server.js
# In a second terminal, generate load:
autocannon http://localhost:3000 -d 30

# 2. Stop the server (Ctrl+C) — clinic generates HTML report automatically

# 3. Flame graph for CPU hotspots
clinic flame -- node server.js
autocannon http://localhost:3000 -d 30

# 4. Bubbleprof for async bottlenecks
clinic bubbleprof -- node server.js
autocannon http://localhost:3000 -d 30

Common Leak Patterns & Fixes

1. Event Listener Leaks

// BAD: adds listener on every request — never removed
app.get('/stream', (req, res) => {
  emitter.on('data', (chunk) => res.write(chunk));  // LEAK
});

// GOOD: remove listener on request close
app.get('/stream', (req, res) => {
  const handler = (chunk) => res.write(chunk);
  emitter.on('data', handler);
  req.on('close', () => emitter.off('data', handler));  // cleanup
});

// GOOD: use once() for one-time events
emitter.once('connected', () => init());

// Monitor listener counts
emitter.setMaxListeners(20);  // warns when exceeded (default: 10)
console.log(emitter.listenerCount('data'));

2. Unbounded Caches

// BAD: Map grows indefinitely
const cache = new Map();
app.get('/data/:id', (req, res) => {
  const result = expensiveCompute(req.params.id);
  cache.set(req.params.id, result);  // LEAK: never evicted
  res.json(result);
});

// GOOD: LRU cache with max size
import LRU from 'lru-cache';
const cache = new LRU({ max: 1000, ttl: 1000 * 60 * 5 }); // 1000 entries, 5min TTL
app.get('/data/:id', (req, res) => {
  if (cache.has(req.params.id)) return res.json(cache.get(req.params.id));
  const result = expensiveCompute(req.params.id);
  cache.set(req.params.id, result);
  res.json(result);
});

3. Closure Capturing Large Data

// BAD: callback captures entire largeData in closure
async function processReport(id: string) {
  const largeData = await fetchLargeDataset(id);  // 50MB object
  const summary = largeData.items.length;

  // This setTimeout keeps largeData alive for 5 minutes!
  setTimeout(() => {
    console.log(`Report ${id} processed: ${summary} items`);
    // largeData is captured in closure even though unused
  }, 300_000);
}

// GOOD: capture only what you need
async function processReport(id: string) {
  const largeData = await fetchLargeDataset(id);
  const summary = largeData.items.length;
  // largeData is no longer referenced after this line — GC can collect it
  setTimeout(() => console.log(`Report ${id}: ${summary} items`), 300_000);
}

Production Memory Monitoring

// Prometheus metrics for memory (with prom-client)
import client from 'prom-client';

const heapGauge = new client.Gauge({
  name: 'nodejs_heap_used_bytes',
  help: 'Node.js heap used in bytes',
});

setInterval(() => {
  heapGauge.set(process.memoryUsage().heapUsed);
}, 15_000).unref();

// Alert in Grafana when:
// - heapUsed grows > 10MB/hour for 3 hours straight
// - heapUsed > 80% of --max-old-space-size limit

# Start with memory ceiling (crash fast rather than degrade)
node --max-old-space-size=512 server.js  # 512MB limit