JavaScript Promise reject() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Static method

Definition

Promise.reject(reason) returns a new promise that is already rejected. A rejected promise means “this failed”, and reason says why. A catch() handler receives that reason, a little later, after the current code has finished. Use it when a function must return a failure instead of throwing one.

Remember
Promise.reject(reason)   → a new rejected promise

.catch(fn)   → fn(reason) runs after the sync code
reason       → best as an Error object (it has a stack)
no handler   → Node.js stops with an error

Syntax

Call reject on the Promise constructor with one value, the reason for the failure.

JavaScript
Promise.reject(reason)
CallWhat it does
Promise.reject(new Error("..."))Reject with an Error object. This is the best habit: it keeps a stack trace.
Promise.reject("text")Reject with any value, such as a string. It works, but there is no stack.
Promise.reject().catch(fn)Reject with undefined. Avoid it: it hides the cause.

Built into JavaScript since ES2015 (ES6).

Library declarations
JavaScript
Promise.reject(reason)   // returns a new Promise

// reason: any value (use an Error object)

Parameters

ParameterDescription
reasonOptional. Why the promise failed. Any value works, but an Error object is best because it has message and stack. The handler gets it exactly as given.

Return Value

Return ValueDescription
PromiseA new rejected promise. Even when reason is a promise, it is not unwrapped.

JavaScript Examples

Example 1 — Create a Rejected Promise and Catch It

Build a promise that fails on purpose, then handle it with catch(). Watch the order of the output lines.

JavaScript
const failed = Promise.reject(new Error('Out of stock'));
console.log('Promise created');

failed.catch((error) => {
  console.log('Caught: ' + error.message);
  console.log(error instanceof Error);
});

console.log('Sync code finished');
Try It Yourself

How It Works

  1. Already rejected. Promise.reject(new Error(...)) returns a promise whose state is rejected from the first moment. No timer or network call is involved.
  2. Plain code goes first. Both top-level console.log lines print before the catch callback, because promise callbacks always wait until the current code has finished.
  3. The reason arrives unchanged. The callback receives the same Error object, so error.message works and error instanceof Error is true.

Example 2 — Reject with an Error, Not a String

You can reject with any value. Compare a string with an Error object and see what the handler can learn.

JavaScript
const withString = Promise.reject('Bad input');
const withError = Promise.reject(new Error('Bad input'));

withString.catch((reason) => {
  console.log('string reason -> type: ' + typeof reason + ', has stack: ' + (typeof reason.stack === 'string'));
});

withError.catch((reason) => {
  console.log('Error reason  -> type: ' + typeof reason + ', has stack: ' + (typeof reason.stack === 'string'));
  console.log('name: ' + reason.name + ', message: ' + reason.message);
});
Try It Yourself

How It Works

  1. Two failures, two kinds of reason. Both promises are rejected with the same words, but one reason is a string and the other is an Error object.
  2. A string is only text. It has no stack property, so nobody can tell which line started the failure.
  3. An Error explains itself. It carries name, message, and stack, so handlers and logs can say far more than a bare string.

Example 3 — Return a Rejection from a Validator

A helper that always returns a promise: fulfilled for a good age, rejected for a bad one. The caller uses await with try/catch.

JavaScript
function parseAge(text) {
  const age = Number(text);
  if (Number.isNaN(age)) {
    return Promise.reject(new Error('Age must be a number'));
  }
  if (age < 0) {
    return Promise.reject(new Error('Age cannot be negative'));
  }
  return Promise.resolve(age);
}

async function run() {
  for (const text of ['25', 'abc', '-3']) {
    try {
      const age = await parseAge(text);
      console.log('"' + text + '" -> age ' + age);
    } catch (error) {
      console.log('"' + text + '" -> ' + error.message);
    }
  }
}

run();
Try It Yourself

How It Works

  1. Return a failure instead of throwing. parseAge() is a normal function, but bad input gives Promise.reject(...). Callers always get a promise, whatever the input was.
  2. await turns it back into an exception. Inside an async function, await on a rejected promise throws the reason, so the catch block can print its message.
  3. Good input still works. "25" gets Promise.resolve(age), so the loop prints the age and moves on to the next text.

Browser & Runtime Support

Promise.reject() is part of ES2015 (ES6), together with the Promise object itself.

✓ Baseline · ES2015

Promise.reject()

Supported in every modern browser, plus Node.js, Deno, and Bun.

98% Modern browser support
Google Chrome All modern versions
Full support
Mozilla Firefox All modern versions
Full support
Apple Safari All modern versions
Full support
Microsoft Edge All modern versions
Full support
Node.js All current releases
Supported
Deno All releases
Supported
Internet Explorer No native support
Not supported
Promise.reject() Excellent

Bottom line: Safe in every modern browser and runtime. The examples print plain strings only, so the output is the same in Node.js and in the browser.

Frequently Asked Questions

It returns a new promise that is already rejected, with the value you pass as the reason. Use catch() to read the reason.
Use an Error object. It has a message and a stack trace that show where the problem started. A string is just text.
It is an unhandled rejection. Node.js 15 and newer stops the program, and browsers print "Uncaught (in promise)" in the console. Add catch() or use try/catch with await.
Not quite. throw stops the current function at once. Promise.reject() returns a failed promise and the code keeps running. Inside then(), both a throw and a returned rejected promise reject the next promise.
No. Promise.reject(p) makes a new rejected promise whose reason is the promise p itself. Only resolve follows promises.

Next: Promise.resolve()

Create a promise that is already fulfilled, and learn when it reuses the promise you give it.

resolve() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful