Parse Node.js Unhandled Promise Rejection

Understanding Node.js Unhandled Promise Rejections

An UnhandledPromiseRejectionWarning occurs when a Promise is rejected but no .catch() handler or try/catch in an async function is present to handle the error. Starting from Node.js 15, unhandled rejections terminate the process by default.

Stack Trace Format

UnhandledPromiseRejectionWarning: Error: Connection refused
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1141:16)
    at Protocol._enqueue (/app/node_modules/mysql/lib/protocol/Protocol.js:144:48)
    at Connection.query (/app/node_modules/mysql/lib/Connection.js:198:25)
    at DatabaseService.findUser (/app/src/services/database.ts:87:12)
    at UserController.getUser (/app/src/controllers/user.ts:34:20)

Async Stack Trace Challenges

Promise-based code creates asynchronous boundaries that can break the stack trace chain. Before Node.js 12 added --async-stack-traces, you might see a truncated trace that only shows the rejection point, not the full async call chain. Modern Node.js (16+) provides much better async stack traces by default.

Key Differences from Synchronous Errors

• The error may be thrown inside a .then() callback or an async function
• The stack trace might include internal Node.js event loop frames (processTicksAndRejections, asyncRunEntryPoint)
• Multiple unhandled rejections can fire from the same root cause if errors propagate through parallel promises

Prevention Strategies

• Always add .catch() to promise chains
• Use try/catch in every async function
• Add a global handler: process.on('unhandledRejection', handler)
• Use ESLint rules like no-floating-promises to catch missing handlers at compile time