creation
Promise.reject
Returns a promise that is already rejected with the given reason. Useful for early-exit paths in functions that must always return a promise.
Promise.reject(reason)Parameters
| Parameter | Purpose |
|---|---|
| reason | Rejection reason — conventionally an Error instance |
| no thenable adoption | Unlike resolve, reject does NOT unwrap thenables |
| immediate | Handlers fire on the next microtask |
Examples
function requireAuth(token) {
if (!token) return Promise.reject(new Error('missing token'));
return fetchUser(token);
}Keeps the return type consistently a promise.
Promise.reject(new Error('nope'))
.catch(err => console.log(err.message)); // 'nope'Straightforward rejection captured by .catch.
// Unhandled rejections are dangerous — always .catch
const p = Promise.reject('lost');
// triggers unhandledrejection unless a handler is attached in timeUncaught rejections fire the unhandledrejection event and may crash Node 15+.
Gotcha
Prefer Error objects over strings for reasons — you lose the stack trace with primitives. Even a rejected promise created for a fast fail path needs a .catch (or an await inside try) somewhere down the line.
Related
Promise.resolve
Returns a promise fulfilled with the given value, or — if the value is already a promise or thenable — the same/adopted promise. Handy for normalizing 'might be a promise' inputs.
new Promise
Constructs a promise from an executor function that receives resolve and reject callbacks. Use it to adapt callback-based or event-based APIs into promises.
unhandledrejection event
Fires when a promise rejects and has no rejection handler attached by the end of the current microtask cycle. Provides a last-chance hook to log or report the error before the runtime warns or exits.
Promise.withResolvers
Creates a promise and exposes its resolve and reject callbacks alongside it, avoiding the need to capture them from a new Promise executor. Added in ES2024 for the 'deferred' pattern.
← All JS Promise reference · async/await vs promises vs callbacks