Signal an asynchronous failure
Return a rejected promise from a function when validation or preconditions fail.
JavaScript · Function
Promise.reject
Promise.reject() creates and returns a new promise that is already rejected with the supplied reason. It is useful for producing rejection branches or adapting a value into a rejected promise.
How it works
Promise.reject(reason) creates an already-rejected promise whose rejection reason is the supplied value. It always creates a new Promise, can be used with Promise subclasses, and is equivalent in effect to constructing a promise whose executor calls reject(reason).
Syntax
Promise.reject(reason)Parameters
| Name | Type | Description |
|---|---|---|
reason | any | Reason why this Promise rejected. |
Returns
A Promise that is rejected with the given reason.
Key points
- Use the static method to create a rejected promise carrying any chosen reason.
- It provides a concise alternative to constructing a promise and calling its reject callback.
- The method can be called with a compatible constructor, not only the built-in Promise constructor.
- A custom constructor must accept an executor function with resolve and reject callbacks.
- Calling it never returns the original promise supplied as the reason.
Common mistakes
- The supplied value is always wrapped in a new promise, even when it is already a promise.
- Prefer an Error object as the reason when you want useful debugging information and selective error handling.
Example: Reject and handle a promise
Promise.reject(new Error("Request failed"))
.catch((error) => console.error(error.message));Creates an immediately rejected promise and handles its reason with catch().
When to use it
Test rejection handling
Create predictable failure inputs for promise-chain or async-handler tests.
Normalize an error path
Convert a synchronous error value into a rejected promise for a uniform async API.
Related
PromisePromise.resolve()Promise.prototype.catch()Promise.prototype.then()