How to fix Warning: Memory leak detected. Unresolved promise prevents garbage collection in Node.js

What this error means

This error indicates that one or more promises in your Node.js application have not been resolved or rejected, and the references to these promises are preventing the garbage collector from reclaiming memory. In JavaScript, promises maintain references to their callbacks (resolve/reject handlers) and any data captured in closures. When a promise never settles (remains in a pending state indefinitely), all these references stay in memory. If this pattern repeats—such as in loops, recursive chains, or long-running processes—the accumulated unresolved promises can consume significant memory. This is particularly problematic with infinite promise chains, where each promise depends on the next one's resolution. Since the Promises/A+ specification requires that promises in a chain cannot be garbage collected until the entire chain resolves, an infinite or very long chain will continuously grow in memory until the process crashes.

Typical symptoms

• Gradual memory increase over time when monitoring Node.js heap usage
• Application eventually crashes with "JavaScript heap out of memory" error
• Memory profiling tools show increasing promise-related allocations
• Performance degradation as memory pressure increases
• Warning messages about possible EventEmitter memory leaks
• Process becomes unresponsive before crashing

Common causes

1. Promises created in loops or recursive functions that never resolve
2. Missing error handling causing promises to remain pending on failures
3. Infinite promise chains where each promise depends on the next
4. Promise.race() or Promise.any() with promises that never settle
5. Async operations without timeouts that hang indefinitely
6. Retry logic that creates new promise chains without resolving old ones
7. Event listeners or callbacks that create promises but never complete
8. Network requests or I/O operations that timeout but promises remain pending

How to fix "Warning: Memory leak detected. Unresolved promise prevents garbage collection"

function promiseWithTimeout(promise, timeoutMs = 5000) {
  return Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Operation timed out')), timeoutMs)
    )
  ]);
}

// Usage
const result = await promiseWithTimeout(
  fetch('https://api.example.com/data'),
  3000
);

// BAD: Creates infinite chain
async function retryForever() {
  try {
    return await riskyOperation();
  } catch (error) {
    return retryForever(); // Chain grows indefinitely
  }
}

// GOOD: Break the chain
function retryWithLimit(maxRetries = 5) {
  let attempts = 0;

  function attempt() {
    return riskyOperation().catch(error => {
      attempts++;
      if (attempts >= maxRetries) {
        throw error;
      }
      // Don't return - creates new chain instead
      return new Promise(resolve =>
        setTimeout(() => resolve(attempt()), 1000)
      );
    });
  }

  return attempt();
}

// BAD: Missing catch can leave promise pending
async function processData(items) {
  const promises = items.map(item => saveToDatabase(item));
  return Promise.all(promises);
}

// GOOD: Handle errors to ensure settlement
async function processData(items) {
  const promises = items.map(item =>
    saveToDatabase(item).catch(error => {
      console.error(`Failed to save item ${item.id}:`, error);
      return null; // Resolve with null instead of hanging
    })
  );

  const results = await Promise.all(promises);
  return results.filter(r => r !== null);
}

const controller = new AbortController();
const signal = controller.signal;

// Set timeout
setTimeout(() => controller.abort(), 5000);

try {
  const response = await fetch('https://api.example.com/data', { signal });
  const data = await response.json();
  console.log(data);
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request was aborted');
  } else {
    throw error;
  }
}

// Add to your application for debugging
const v8 = require('v8');
const fs = require('fs');

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

// Take snapshots before and after suspected leak
takeHeapSnapshot();
// ... run your code
setTimeout(takeHeapSnapshot, 60000);

const pendingPromises = new Set();

function trackPromise(promise, label) {
  const tracked = { promise, label, created: Date.now() };
  pendingPromises.add(tracked);

  promise.finally(() => {
    pendingPromises.delete(tracked);
  });

  return promise;
}

// Periodically check for old promises
setInterval(() => {
  const now = Date.now();
  pendingPromises.forEach(p => {
    const age = now - p.created;
    if (age > 10000) { // 10 seconds
      console.warn(`Long-pending promise: ${p.label} (${age}ms old)`);
    }
  });
}, 5000);

// Usage
await trackPromise(fetchData(), 'User data fetch');

Advanced notes

Frequently asked questions

What does "Warning: Memory leak detected. Unresolved promise prevents garbage col" mean?

js application have not been resolved or rejected, and the references to these promises are preventing the garbage collector from reclaiming memory. In JavaScript, promises maintain references to their callbacks (resolve/reject handlers) and any data captured in closures. When a promise never settles (remains in a pending state indefinitely), all these references stay in memory.

How do I fix "Warning: Memory leak detected. Unresolved promise prevents garbage col"?

This warning occurs when promises remain unresolved indefinitely, preventing JavaScript's garbage collector from freeing memory. Long-lived or infinite promise chains accumulate in memory, eventually leading to performance degradation or out-of-memory crashes.

What causes "Warning: Memory leak detected. Unresolved promise prevents garbage col"?

Promises created in loops or recursive functions that never resolve Missing error handling causing promises to remain pending on failures Infinite promise chains where each promise depends on the next

Is the "Warning: Memory leak detected. Unresolved promise prevents garbage col" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• Error: Promise never resolved or rejected (promise pending indefinitely)

  Promise never resolved or rejected

  HIGH

• Unhandled promise rejection from Promise.all()

  Error from Promise.all() when one promise rejects

  HIGH

• TypeError: value is not a function or its return value is not a promise

  Value is not a function or its return value is not a promise

  MEDIUM

• Error: Uncaught exception in main process (unhandled error)

  Uncaught Exception in Main Process

  CRITICAL

• Error: zlib error Z_DATA_ERROR (corrupted compressed data)

  Z_DATA_ERROR: Corrupted compressed data

  MEDIUM

• Error: Could not find package.json in current directory (npm module resolution)

  How to fix "Could not find package.json in current directory" in Node.js

  MEDIUM

Official resources & further reading

• 📚Node.js Official Documentation
• 🐙
  Promise.race Memory Leak with Unresolved Promises(GitHub)
• 📝
  Infinite Recursive Promise Resolution Chains
• 📝
  4 Types of Memory Leaks in Node.js and How to Avoid Them
• 🐙
  Memory Leak on Promise.all with async/await(GitHub)