How should I surface and handle AggregateError.errors when Promise.any() rejects so failures are actionable?

Promise.any() is often introduced as the promise combinator that returns the first fulfillment value. That mental model is correct, but incomplete in the exact case that causes trouble in production: every candidate source fails. In that situation, the operation does not expose one “real” error and discard the rest. It rejects with an AggregateError that carries the full set of rejection reasons. The important consequence is that the failure is not about one promise winning or losing a race. It is about a batch of sources all being unsuitable, and the caller now owns the choice of what to do next.

That distinction matters when Promise.any() fronts multiple mirrors, caches, endpoints, or fallback providers. If the caller treats the rejection as a single-source failure, the handling code can misclassify the incident. A transient timeout on one source may deserve a retry, while an authentication failure or a malformed response may deserve an immediate fatal path. AggregateError exists precisely because the runtime had several unrelated failures to report, and the caller needs access to the set, not just the existence of rejection.

MDN documents both parts of that contract: Promise.any() fulfills with the first success, and if all inputs reject, the returned promise rejects with an AggregateError whose errors array contains the rejection reasons in input order. That ordering guarantee is the piece that makes deterministic handling possible. Once the sources are labeled before aggregation, the rejection becomes structured enough to support retry and fallback decisions instead of a generic catch-all branch.

• When every input rejects, Promise.any() does not surface one special loser; it rejects with an AggregateError.
• The useful part is the errors array, which keeps the same order as the input promises, not the order in which they failed.
• If you label each source before calling Promise.any(), the batch failure becomes a decision list instead of a mystery exception.

The simplest way to make an AggregateError actionable is to attach metadata before the promises go into Promise.any(). The supplied fixture does this by wrapping each source in an object with a stable label, then converting each rejection into an Error that carries two pieces of information: the sourceLabel and the originalReason. That wrapper is not trying to change Promise.any() itself. It is making the rejection reasons inspectable in the same shape they will later have in the AggregateError.errors array.

This is a better boundary than trying to infer the source after the fact. Without labels, a rejection reason may tell you that a network request failed or that a server returned a bad payload, but it will not reliably tell you which origin, mirror, or fallback route produced that result. If all you have is the rejection reason, your handler has to guess. If you preserve labels alongside reasons, the handler can make an explicit decision: retry the labeled source, skip it, or report that specific source as fatal.

The practical rule is simple: label the source at the point where you still know what it is. Do not wait until the catch block and hope the error text identifies the origin. Promise.any() gives you ordered reasons, but it does not invent domain labels for you. Your code must supply those labels if you want the later error handling to stay deterministic and understandable.

• The runtime preserves the order of the input promises in AggregateError.errors, even if the promises settle in a different order.
• That means you can attach a stable label to each input before aggregation and recover that label from the error list later.
• A deterministic test should assert the input order, the labels, and the original reasons separately.

A good regression test for this pattern needs to prove more than “the promise rejects.” It has to prove that the failure shape is the one the application logic expects. In the fixture, three labeled sources reject for different reasons. One uses an Error instance, one uses a string, and one uses a plain object. That mix is deliberate. It shows that the handler cannot rely on one narrow error type and that the label metadata survives even when the reason itself is not an Error object.

The key assertion is that Promise.any() throws an AggregateError when all inputs fail and that the AggregateError.errors array preserves the original input order. That is the ordering guarantee the application uses to map the failure back to the labeled source. If the order were unstable, a decision table built from the aggregated reasons would become unreliable. By checking the labels and the reasons independently, the test guards against two different mistakes: losing source identity and accidentally reordering the batch before handling it.

This kind of test is especially useful because Promise.any() can hide a lot of concurrency noise. One source may fail immediately and another may fail later, but the aggregated error list is not a chronology. It is a source-indexed report. The test should protect that distinction so a future refactor does not accidentally treat completion order as meaning order.

• The example uses three labeled sources that fail for different reasons, including an Error, a string, and an object.
• The test asserts that Promise.any() rejects, that the AggregateError has three errors, and that the labels are still aligned with the original inputs.
• A second assertion checks that the reasons are recoverable in the same order as the inputs, which is the contract the handler depends on.

Once you have an AggregateError with labeled entries, the next step is not to ask whether the whole operation succeeded or failed. You already know it failed. The real question is which failures are retryable and which failures mean the source should be removed from the current decision path. The fixture’s classifyAggregateError helper turns the AggregateError.errors list into two arrays: retryable and fatal. Each entry keeps the source label and the original reason together so the downstream logic can keep the decision local to a particular source.

That separation is useful because operational reasons differ. A network error, timeout, or connection reset often suggests a retry on the same source or a retry against another source. A not-found or schema mismatch error may indicate that the source is unsuitable, but retrying the same request is unlikely to help. In other words, Promise.any() tells you that no source won the race; your classification logic tells you why each candidate lost and what kind of next step is sensible.

The helper also shows a conservative default. If the retryability predicate itself throws, the source is treated as fatal. That choice avoids replacing one missing decision with another unhandled exception. It is not a universal policy, but it is a practical one: classification should preserve evidence and keep the caller in control. The important part is that the decision is made per source, not at the level of the whole batch.

• Classify each aggregated entry with a predicate that answers “retryable or fatal?” rather than trying to recover from the entire batch at once.
• Keep the per-source label with the reason in the classification output so downstream code can act on one source at a time.
• If the classifier itself fails, treat the source as fatal rather than losing the whole batch to a secondary error.

Promise.any() is not a general substitute for every fallback workflow. It is designed to return the first fulfillment, which means it is excellent when success is enough and the caller does not need all results. It is not a cancellation primitive, and it is not a monitor for source-side resource cleanup. MDN notes that once Promise.any() is called, the input promises are marked as handled, but the remaining work is not cancelled automatically. If a fallback source keeps running after another source succeeds, the runtime still expects your application to manage that cost.

A second limit is that the errors array is ordered by input position, not by completion time. That is exactly what makes the batch deterministic, but it also means the list is a structural report rather than a chronological trace. If you need to explain the timing of failures, you still need timestamps, logging, or per-source instrumentation. The aggregated error only tells you which source was which and what reason each one produced.

A third edge case is the empty iterable. Promise.any() rejects there too, because no promise can fulfill from an empty list. That is not a special “all failed” case, but it still reaches the same rejection boundary. A robust caller therefore needs to treat the empty input case as part of the same decision surface: there is no winning source, and the application must choose whether to report a configuration problem, rebuild the source list, or fall back to a different strategy altogether.

• An empty iterable also rejects, so the caller still needs a catch path even when the input list is built dynamically.
• Promise.any() does not cancel remaining work after the first fulfillment, so source-side cleanup remains your responsibility.
• Ordered errors help the caller reason about the batch, but they do not tell you whether a source failed before or after another one.

The supplied fixture is intentionally small because its job is to isolate the contract boundary. It proves that Promise.any() resolves on the first success, rejects when every input fails, and produces an AggregateError that can be inspected through its errors array. It also proves that the label-preserving wrapper keeps source identity visible when the batch fails, which is the part the caller needs in order to decide what happens next.

The fixture does not try to simulate an entire production fallback system. It does not implement cache eviction, retry backoff, circuit breaking, or source health scoring. Those are useful features, but they are separate design decisions. The article’s point is narrower: if you already have several labeled sources and you are racing them with Promise.any(), then the fully failing case should not be treated as a single anonymous exception. It should be interpreted as a structured report with one entry per source.

That is why the article focuses on a deterministic test pattern. The test protects the ordering rule, the presence of the AggregateError, and the availability of the per-source reasons. Once those are guaranteed, the caller can build the next step it actually wants: retry a transient source, fall back to a known-good mirror, or surface a fatal incident with enough detail to be useful. The runtime gives you the batch; your code decides what the batch means.

• The fixture proves the shape of the rejection and the classification strategy, but it does not prove real network behavior.
• The tests do not establish cancellation, retry backoff, or source health checks; those remain application responsibilities.
• The operational value comes from turning a single AggregateError into a labeled set of next actions.