Promise.reject() creates a Promise that is already rejected with a reason. It is useful when you want to return a failed asynchronous result from a function, simulate an error in tests, or stop a promise chain with a controlled rejection.
A rejected promise must be handled with .catch(), the rejection callback of .then(), or try...catch around await. Otherwise, JavaScript may report an unhandled promise rejection.
Tested On: The examples were tested with Node.js v20.18.1 on a Linux system. The same Promise rejection behavior works in modern browsers and JavaScript runtimes.
JavaScript Promise.reject Syntax
Promise.reject(reason)reason can be any value, but using an Error object is usually better for debugging because it includes an error type, message, and stack trace.
Method 1: Reject a Promise and Handle It with catch()
Use .catch() to handle the rejected promise.
Promise.reject(new Error("failed"))
.catch((error) => {
console.log("reject-catch:", error.message);
});Tested output:
reject-catch: failedThis is the most common pattern when a function returns a promise chain.
Method 2: Reject with a Simple Reason
Although an Error object is preferred, Promise.reject() can reject with a string, number, object, or any other value.
Promise.reject("manual")
.catch((reason) => {
console.log("reject-string:", reason);
});Tested output:
reject-string: manualFor application code, use strings only for small demos or controlled values. Use new Error("message") when the rejection represents a real failure.
Method 3: Return Promise.reject from a Function
Promise.reject() is useful when a function must always return a promise, even for validation failures.
function loadUser(id) {
if (!id) {
return Promise.reject(new Error("User ID is required"));
}
return Promise.resolve({ id, name: "Ana" });
}
loadUser(null).catch((error) => console.log(error.message));Output:
User ID is requiredThis keeps the function's return type consistent: callers always handle a promise.
Method 4: Handle Promise.reject with async and await
Inside an async function, use try...catch around await.
async function run() {
try {
await Promise.reject(new Error("Async failed"));
} catch (error) {
console.log(error.message);
}
}
run();Output:
Async failedThis pattern reads like synchronous error handling while still working with promises.
Promise.reject vs throw
Inside a .then() callback or an async function, throwing an error also creates a rejected promise for the caller.
Promise.resolve()
.then(() => {
throw new Error("Thrown inside chain");
})
.catch((error) => console.log(error.message));Output:
Thrown inside chainUse throw inside promise callbacks or async functions. Use Promise.reject() when you need to directly create and return an already rejected promise.
Common Questions About Promise Rejection
What does Promise.reject do?
Promise.reject() returns a promise that is rejected with the reason you pass to it. The rejection is handled by .catch(), .then(null, handler), or try...catch with await.
Should I reject with Error or a string?
Prefer Error objects for real failures. They make debugging easier and preserve stack information. Strings are acceptable for short examples but are weaker in production code.
Is Promise.reject the opposite of Promise.resolve?
Conceptually yes: Promise.resolve() creates or adopts a fulfilled promise, while Promise.reject() creates a rejected promise. One key difference is that Promise.reject() wraps its reason in a new rejected promise even if that reason is already a promise.
Summary
Promise.reject() is the JavaScript shortcut for creating an already rejected promise. Use it for validation failures, controlled async errors, tests, and promise-returning APIs. Handle the rejection with .catch() or try...catch with await, and prefer rejecting with Error objects so failures are easier to diagnose.
