Promise.reject()

Updated March 13, 2026 · Async APIs

javascript promise async

The Promise.reject() static method returns a Promise object that is rejected with the given reason. It is one of the two Promise resolution methods in JavaScript, alongside Promise.resolve().

Syntax

Promise.reject(reason)

Parameters

reason: The reason for the rejection. This can be any JavaScript value, including errors, strings, objects, or undefined.

Return Value

A Promise that was rejected with the specified reason.

Description

Promise.reject() is a static method on the Promise constructor that creates a new rejected Promise immediately, without requiring an executor function. This method exists primarily for consistency with Promise.resolve(), allowing you to create rejected promises in a fluent, functional style.

The method accepts any value as its reason argument. While it is conventional to pass an Error object (or a subclass like TypeError, RangeError), JavaScript does not enforce this. Passing non-Error values is valid but generally discouraged because it loses stack trace information.

When to Use Promise.reject()

This method is useful in several scenarios:

Conditional rejection: When a function needs to return a rejected Promise based on some condition, Promise.reject() provides a clean syntax without requiring an async function or executor.
Testing: Creating intentionally rejected Promises is essential for testing error handling code, particularly with methods like Promise.all(), Promise.race(), or custom promise utilities.
API design: Libraries that return Promises can use Promise.reject() to signal failures without exposing internal executor logic.

Comparison with throw

Unlike throwing an error inside an async function (which causes the returned Promise to reject), Promise.reject() creates the rejected Promise explicitly. This can be clearer in conditional logic where you want the rejection path to be immediately visible:

function getData(id) {
  if (!id) {
    return Promise.reject(new Error("ID is required"));
  }
  return fetch(`/api/data/${id}`);
}

Examples

Basic Usage

Creating a simple rejected Promise with an Error:

const rejectedPromise = Promise.reject(new Error("Something went wrong"));

rejectedPromise.catch((error) => {
  console.log(error.message); // "Something went wrong"
  console.log(error instanceof Error); // true
});

Using with Non-Error Values

While not recommended, any value can be used as the rejection reason:

const p = Promise.reject("failure reason");

p.catch((reason) => {
  console.log(reason); // "failure reason"
  console.log(typeof reason); // "string"
});

Conditional Promise Return

The method shines when you need to conditionally return rejected or resolved Promises:

function validateAndFetch(user) {
  if (!user || !user.id) {
    return Promise.reject(new TypeError("Invalid user object"));
  }
  return fetch(`/users/${user.id}`);
}

validateAndFetch({ id: 42 })
  .then((response) => console.log("Success:", response))
  .catch((err) => console.error("Error:", err.message));

In Promise.all() for Error Collection

When you need to handle multiple Promises but want to track both successes and failures, you can use Promise.reject() to convert individual failures into the collection:

const results = [
  Promise.resolve(1),
  Promise.reject(new Error("Second failed")),
  Promise.resolve(3)
];

Promise.allSettled(results).then((outcomes) => {
  outcomes.forEach((outcome, index) => {
    if (outcome.status === "fulfilled") {
      console.log(`Promise ${index}:`, outcome.value);
    } else {
      console.log(`Promise ${index}:`, outcome.reason.message);
    }
  });
});

Chaining with Promise.race()

In race conditions where you want a timeout-style rejection:

function withTimeout(promise, ms) {
  return Promise.race([
    promise,
    Promise.reject(new Error(`Timed out after ${ms}ms`))
  ]);
}

const slow = new Promise((resolve) => setTimeout(resolve, 2000));
withTimeout(slow, 100).catch((err) => console.log(err.message)); // "Timed out after 100ms"