Skip to content

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

javascript
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

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary