AggregateError — Klasse · JavaScript-Referenz

Signatur

class AggregateError extends Error

Beschreibung

AggregateError ist ein spezieller Fehlertyp, der eine Sammlung von Einzelfehlern bündelt. Er wurde in ES2021 eingeführt, primär für Promise.any(): Wenn alle übergebenen Promises abgelehnt werden, wirft Promise.any() einen AggregateError, der alle Ablehnungsgründe enthält.

Ein AggregateError verhält sich wie ein normaler Error – er besitzt name, message und stack – ergänzt durch die Eigenschaft errors, ein Array aller enthaltenen Fehler. Die Einträge dieses Arrays können beliebige Werte sein, nicht nur Error-Instanzen.

Eigene AggregateError-Instanzen lassen sich manuell erzeugen, wenn in einer eigenen API mehrere Fehlerquellen gleichzeitig gemeldet werden sollen. Dies ist besonders nützlich bei paralleler Validierung oder beim Sammeln von Fehlern aus mehreren asynchronen Operationen.

Abfangen: Mit catch (e) und anschließendem e instanceof AggregateError prüfen.
Einzelfehler lesen: Über e.errors iterieren.

Parameter

Name	Typ	Default	Beschreibung
$errors Pflicht	Iterable<any>		Ein iterierbares Objekt (z. B. Array) der einzelnen Fehler oder Werte, die zusammengefasst werden sollen. Die Elemente werden als `errors`-Array gespeichert.
$message	string	""	Eine optionale, menschenlesbare Fehlermeldung für den `AggregateError` als Ganzes. Verfügbar über `.message`.
$options	{ cause?: any }	{}	Optionales Objekt mit einer `cause`-Eigenschaft (ES2022+), die den ursprünglichen Auslöser des Fehlers angibt. Verfügbar über `.cause`.

Rückgabewert

Typ

AggregateError

Beschreibung

Eine neue AggregateError-Instanz, die alle übergebenen Einzelfehler im errors-Array enthält und als vollwertiger Error geworfen werden kann.

Beispiele

AggregateError aus Promise.any() abfangen

const p1 = Promise.reject(new Error('Netzwerkfehler'));
const p2 = Promise.reject(new TypeError('Ungültiger Typ'));
const p3 = Promise.reject(new RangeError('Wert außerhalb des Bereichs'));

try {
  await Promise.any([p1, p2, p3]);
} catch (e) {
  if (e instanceof AggregateError) {
    console.log(e.message);       // "All promises were rejected"
    console.log(e.errors.length); // 3
    e.errors.forEach((err, i) => {
      console.log(`Fehler ${i + 1}:`, err.message);
    });
  }
}

All promises were rejected 3 Fehler 1: Netzwerkfehler Fehler 2: Ungültiger Typ Fehler 3: Wert außerhalb des Bereichs

Eigenen AggregateError für parallele Validierung erzeugen

const validateUser = (user) => {
  const errors = [];

  if (!user.name) {
    errors.push(new Error('Name darf nicht leer sein.'));
  }
  if (!user.email?.includes('@')) {
    errors.push(new Error('E-Mail-Adresse ist ungültig.'));
  }
  if (user.age < 0 || user.age > 120) {
    errors.push(new RangeError('Alter muss zwischen 0 und 120 liegen.'));
  }

  if (errors.length > 0) {
    throw new AggregateError(errors, `Validierung fehlgeschlagen (${errors.length} Fehler)`);
  }

  return true;
};

try {
  validateUser({ name: '', email: 'kein-at', age: -5 });
} catch (e) {
  if (e instanceof AggregateError) {
    console.log(e.message);
    e.errors.forEach(err => console.log('-', err.message));
  }
}

Validierung fehlgeschlagen (3 Fehler) - Name darf nicht leer sein. - E-Mail-Adresse ist ungültig. - Alter muss zwischen 0 und 120 liegen.

// Wichtig · Fallstricke

Browser-Kompatibilität: AggregateError ist seit ES2021 standardisiert und wird von allen modernen Browsern sowie Node.js ab Version 15 unterstützt. Ältere Umgebungen benötigen ein Polyfill.

Unterschied zu Error: Das errors-Array kann beliebige Werte enthalten – nicht nur Error-Instanzen. Bei Promise.any() entsprechen die Einträge den Ablehnungswerten der Promises, die ebenfalls beliebig sein können.

Achtung bei instanceof: Über Iframe- oder Realm-Grenzen hinweg kann instanceof AggregateError fehlschlagen. In solchen Fällen ist e.name === 'AggregateError' eine robustere Prüfmethode.

Siehe auch

Error Promise.any() Promise.allSettled() Promise.all() try...catch