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)
Call
What 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
Parameter
Description
reason
Optional. 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 Value
Description
Promise
A 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.
Promise created
Sync code finished
Caught: Out of stock
true
How It Works
Already rejected.Promise.reject(new Error(...)) returns a promise whose state is rejected from the first moment. No timer or network call is involved.
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.
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.
string reason -> type: string, has stack: false
Error reason -> type: object, has stack: true
name: Error, message: Bad input
How It Works
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.
A string is only text. It has no stack property, so nobody can tell which line started the failure.
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();
"25" -> age 25
"abc" -> Age must be a number
"-3" -> Age cannot be negative
How It Works
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.
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.
Good input still works."25" gets Promise.resolve(age), so the loop prints the age and moves on to the next text.
Compatibility
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 ChromeAll modern versions
Full support
Mozilla FirefoxAll modern versions
Full support
Apple SafariAll modern versions
Full support
Microsoft EdgeAll modern versions
Full support
Node.jsAll current releases
Supported
DenoAll releases
Supported
Internet ExplorerNo 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.