Promise.race
In one line
Promise.race takes an iterable of promises and settles (resolves or rejects) as soon as the first one settles.
In simple words
Promise.race runs multiple promises and settles as soon as the first one does — adopting the first promise's fulfillment value or rejection reason. The other promises continue running but their results are ignored.
This is useful for timeouts: race a real operation against a timer promise, and whichever finishes first wins. If the timer wins, you treat it as a timeout. Promise.race is also used for "first successful source" patterns — query multiple caches and use whichever responds first.
Note that "race" means first to settle, not first to resolve. If the first promise to settle rejects, Promise.race rejects, even if another would have resolved. For "first to resolve, ignore rejections" use Promise.any. The non-first promises are not cancelled — JavaScript promises cannot be cancelled — they just become unobserved.
Example
function withTimeout(promise, ms) {
const timeout = new Promise((_, reject) =>
setTimeout(() => reject(new Error("timeout")), ms)
);
return Promise.race([promise, timeout]);
}
// Resolves if fetch finishes in 5s, otherwise rejects with "timeout"
const result = await withTimeout(fetch("/api/slow"), 5000);Promise.race settles with whichever finishes first. If the timeout fires before the fetch, you get a timeout error.
Related terms
Related Resources
Related Lessons
- Promises
Learn Promise.race.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.