Diagnosing Unhandled Promise Rejections in async/await Code

Recognizable condition

When running JavaScript code that uses async/await, you see a warning like “UnhandledPromiseRejectionWarning” in the browser console or Node.js prints “(node:xxxx) UnhandledPromiseRejectionWarning” and may exit with code 1 (Node 15+).

Cause / diagnostic table

Ordered checks

1. Locate every async function that contains an await without a surrounding try block.
2. For each located function, verify whether the awaited promise can reject (e.g., it calls a network API, file system, or returns Promise.reject).
3. Check if the function returns a promise that is used elsewhere without .catch or await in a try/catch.
4. In Node.js, run node --trace-warnings script.js to see the full stack; in browsers, open the console and look for the warning.
5. Confirm the Node version: node -v. Versions ≥15 enable the warning; <15 may hide it.

Fixes tied to findings

• Missing try/catch – wrap the await in try { await expr; } catch (e) { /* handle */ }.
• Returned rejected promise – either return await expr; inside a try/catch or add .catch on the returned promise where it is used.
• Top‑level await – if using ES modules, add a try/catch around the top‑level await or listen to process.on('unhandledRejection') in Node.
• Global handler missing – attach a listener: process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled', reason); process.exit(1); }) (only after fixing the root cause).

Escalation criteria

If after applying the above checks the warning persists:

• Enable detailed tracing: node --trace-process-warnings --trace-unhandled-rejections script.js.
• Consider using a wrapper library (e.g., p‑limit or async‑hooks) to centralize error handling.
• If the code runs in both browser and Node, verify that the environment‑specific global (window vs process) is handled appropriately.
• As a last resort, upgrade Node to a supported LTS version (≥18) where the warning behavior is well‑documented.