Unhandled Promise Rejection Warning (Node.js)

UnhandledPromiseRejectionWarning in Node.js – Detailed Explanation

The UnhandledPromiseRejectionWarning is a common warning in Node.js that occurs when a promise is rejected, but no .catch() handler or try...catch block is provided to handle the rejection. This can lead to unexpected application behavior and potential crashes in future Node.js versions.

---

Understanding Promises in JavaScript

A promise in JavaScript represents an operation that will complete in the future, either resolving successfully (fulfilled) or failing with an error (rejected). If a promise is rejected but no rejection handler is attached, it results in an unhandled promise rejection.

Basic Promise Example

const myPromise = new Promise((resolve, reject) => {
  reject("This is an error!");
});

In the above code, the promise is rejected, but there is no .catch() method to handle the rejection, which will trigger an UnhandledPromiseRejectionWarning.

---

Understanding UnhandledPromiseRejectionWarning

If an unhandled rejection occurs, Node.js will display a warning like this:

(node:12345) UnhandledPromiseRejectionWarning: Error: Something went wrong!
    at Object.<anonymous> (/path/to/file.js:3:10)
    at Module._compile (internal/modules/cjs/loader.js:1072:14)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1101:10)
    at Module.load (internal/modules/cjs/loader.js:937:32)
    at Function.Module._load (internal/modules/cjs/loader.js:778:12)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:76:12)
(node:12345) UnhandledPromiseRejectionWarning: Unhandled promise rejections are deprecated.

This means that:

1. A promise was rejected, but there was no error handler attached.
2. Node.js detects this and throws a warning to alert the developer.
3. In future versions, this could result in the process exiting with a non-zero code.

---

Common Causes of UnhandledPromiseRejectionWarning

1. Forgetting to Handle Rejections

const failingPromise = new Promise((resolve, reject) => {
  reject("Something went wrong!");
});

// No .catch() provided, causing UnhandledPromiseRejectionWarning

2. Async/Await Without Try-Catch

If you use async/await but forget to handle errors, an unhandled rejection can occur.

async function fetchData() {
  const result = await fetch("https://api.example.com/data");
  const data = await result.json();
  return data;
}

fetchData(); // No error handling leads to an UnhandledPromiseRejectionWarning

3. Returning a Rejected Promise Without a Catch

function asyncFunction() {
  return new Promise((resolve, reject) => {
    reject("Error occurred!");
  });
}

asyncFunction(); // No .catch() attached

4. Not Handling Errors in Promise Chains

fetch("https://invalid-url.com")
  .then(response => response.json())
  .then(data => console.log(data)); // No .catch() for errors

If fetch() fails (e.g., due to network issues), this will cause an UnhandledPromiseRejectionWarning.

---

How to Fix UnhandledPromiseRejectionWarning

1. Add a .catch() to Handle Errors

Always attach a .catch() method to promises to handle errors gracefully.

const myPromise = new Promise((resolve, reject) => {
  reject("Something went wrong!");
});

myPromise.catch(error => {
  console.error("Caught error:", error);
});

2. Use Try-Catch with Async/Await

Wrap await calls inside try...catch blocks to handle errors properly.

async function fetchData() {
  try {
    const result = await fetch("https://api.example.com/data");
    const data = await result.json();
    return data;
  } catch (error) {
    console.error("Error fetching data:", error);
  }
}

fetchData();

3. Use .catch() in Promise Chains

When chaining .then() calls, always provide a .catch() at the end.

fetch("https://invalid-url.com")
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error("Fetch error:", error));

4. Global Error Handling for Unhandled Promise Rejections

If you’re working on a large application, you can catch all unhandled promise rejections globally.

process.on("unhandledRejection", (reason, promise) => {
  console.error("Unhandled Promise Rejection:", reason);
});

While this prevents your application from crashing, it is always better to handle errors where they occur.

---

Preventing Future Unhandled Rejections

Starting from Node.js 15, unhandled promise rejections will terminate the process with a non-zero exit code. To enforce this behavior in older versions, you can use:

process.on("unhandledRejection", (reason) => {
  throw reason; // Converts unhandled rejections into thrown errors
});

This forces the application to crash, making it easier to detect unhandled promise rejections during development.

---