JavaScriptAsyncIntermediate

Promise.any()

Resolves with the first fulfilled promise; rejects if all reject.

Review the syntaxStudy the examplesOpen the coding app
Promise.any([promise1, promise2, ...])
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Resolves with the first fulfilled promise; rejects if all reject.

Promise.any() is a short-circuiting method that settles as soon as any of the input promises fulfills. Unlike Promise.race(), which settles when the first promise either fulfills or rejects, Promise.any() ignores rejections and continues waiting for the first success. This is particularly useful for requesting resources from multiple mirrors or caches where only one successful response is required. From a performance perspective, it allows for high-availability strategies by reducing latency to that of the fastest responding healthy node. Edge cases include passing an empty iterable, which returns a promise that is synchronously rejected with an AggregateError, and scenarios where all promises reject, resulting in an AggregateError containing an array of all rejection reasons in the 'errors' property. Note that IE is not supported as this is an ES2021 feature.

Quick reference

Syntax

Promise.any([promise1, promise2, ...])

Inputs

Parameters

iterableIterable<Promise> · Promises (or values) to try.

See it in practice

Examples

1

Retrieving Data from Mirror Servers

const request1 = new Promise((resolve, reject) => setTimeout(() => reject('Mirror 1 failed'), 100));
const request2 = new Promise((resolve) => setTimeout(() => resolve('Data from Mirror 2'), 250));
const request3 = new Promise((resolve) => setTimeout(() => resolve('Data from Mirror 3'), 500));

Promise.any([request1, request2, request3])
  .then(function(value) {
    console.log(value);
  })
  .catch(function(error) {
    console.error(error);
  });
Output:
"Data from Mirror 2"

Even though Mirror 1 rejected first, Promise.any() ignored it and waited for the first fulfillment from Mirror 2.

2

Handling All Rejections

const p1 = Promise.reject('Network Error');
const p2 = Promise.reject('Timeout');

Promise.any([p1, p2]).catch(function(err) {
  console.log(err.name);
  console.log(err.errors);
});
Output:
"AggregateError" ["Network Error", "Timeout"]

When all promises in the iterable reject, the returned promise rejects with an AggregateError containing the specific reasons.

3

Empty Iterable Edge Case

Promise.any([])
  .catch(function(err) {
    console.log(err.name);
    console.log(err.errors.length);
  });
Output:
"AggregateError" 0

Passing an empty array causes an immediate rejection because there are no promises that could ever fulfill.

Debug faster

Common Errors

1

LogicError

Cause: Confusing Promise.any() with Promise.race().

Fix: Use Promise.any() when you need the first success regardless of previous failures. Use Promise.race() if you need the absolute first promise to settle (even if it is a failure).

// Race will reject if the fastest promise fails
Promise.race([Promise.reject('fail'), Promise.resolve('win')]);
2

AggregateError

Cause: Failing to access the 'errors' property on the caught error object when all promises fail.

Fix: Access the 'errors' property of the AggregateError object to inspect the individual rejection reasons from the input iterable.

Promise.any([p1]).catch(err => {
  // Incorrect: console.log(err);
  // Correct:
  console.log(err.errors);
});

Runtime support

Compatibility

Node.js, BrowserAll modern browsersES2021

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Resolves with the first fulfilled promise; rejects if all reject.

iterable: Promises (or values) to try.

LogicError: Use Promise.any() when you need the first success regardless of previous failures. Use Promise.race() if you need the absolute first promise to settle (even if it is a failure). AggregateError: Access the 'errors' property of the AggregateError object to inspect the individual rejection reasons from the input iterable.