Promise.any()

Added in ves2021· Updated June 2, 2026· Async APIs

promiseasynces2021javascript

Promise.any() is a static method that takes an iterable of promises and returns a single Promise that resolves as soon as any one of the input promises resolves. Unlike Promise.race(), which settles as soon as any promise settles (whether resolved or rejected), Promise.any() waits for the first successful resolution.

If all input promises reject, Promise.any() rejects with an AggregateError, which contains an array of all the rejection reasons.

Syntax

Promise.any(iterable)

Parameters

iterable
- An iterable (such as an Array) of promises or other values to check.

Return Value

A Promise that:

Resolves as soon as any promise in the iterable resolves (with that promise’s value)
Rejects with an AggregateError if all promises in the iterable reject

Description

Promise.any() is useful when you want the first successful result from multiple independent async operations. Think of it as an “OR” operation for promises — you care about the first win, and you don’t care which one wins.

This method is the logical counterpart to Promise.all(), which waits for all promises to resolve, and Promise.race(), which settles with the first promise to settle (success or failure).

AggregateError

When all promises reject, the returned promise rejects with an AggregateError object. This error has two key properties:

errors — an array containing all the rejection reasons
message — a string describing that all promises were rejected

When `Promise.any()` is useful

Promise.any() shines when several sources can answer the same question and you only need one successful response. A classic example is trying multiple mirrors, caches, or service endpoints and accepting the first one that works. Unlike Promise.race(), it ignores early rejections, so a single failure does not spoil the whole attempt. That makes it a good fit for resilient request flows where success from any one source is enough.

Working With AggregateError

The rejection case is still important to handle because Promise.any() only succeeds when at least one promise resolves. If every input rejects, the resulting AggregateError gives you the list of failures so you can log them or surface a summary. That is useful for debugging distributed systems, where several backends might fail for different reasons and you want to see the full picture instead of just the first error.

Examples

First successful resolution

const p1 = new Promise((resolve, reject) => {
  setTimeout(() => reject('first failure'), 100);
});

const p2 = new Promise((resolve) => {
  setTimeout(() => resolve('second success'), 50);
});

const p3 = new Promise((resolve) => {
  setTimeout(() => resolve('third success'), 75);
});

Promise.any([p1, p2, p3])
  .then((value) => {
    console.log(value); // Output: "second success"
  });

The example above shows Promise.any() resolving with the first success — p2 at 50ms — while ignoring p1’s rejection entirely. The next example demonstrates the opposite case: every input rejects, so Promise.any() has no winner to pick. The resulting AggregateError bundles all rejection reasons together, letting you inspect every failure rather than just the first one.

Handling AggregateError

const p1 = Promise.reject('Error 1');
const p2 = Promise.reject('Error 2');
const p3 = Promise.reject('Error 3');

Promise.any([p1, p2, p3])
  .catch((aggregateError) => {
    console.log(aggregateError.errors);
    // Output: ["Error 1", "Error 2", "Error 3"]
  });