AggregateError: errors — Eigenschaft · JavaScript-Referenz

Signatur

aggregateError.errors

Beschreibung

Die Eigenschaft errors gehört zu jeder Instanz von AggregateError und enthält ein Array mit den Einzelfehlern, die zu einem Fehler zusammengefasst wurden. Beim Aufruf von new AggregateError(iterable, message) wird das übergebene Iterable einmal durchlaufen und in ein neues Array kopiert. Dieses Array steht dann unter errors bereit.

Am häufigsten begegnet man errors bei Promise.any(): Werden alle übergebenen Promises abgelehnt, lehnt Promise.any() mit einem AggregateError ab. Dessen errors-Array enthält die Ablehnungsgründe in derselben Reihenfolge wie die Eingabe-Promises, also nicht in der Reihenfolge, in der sie abgelehnt wurden.

Auch im eigenen Code ist die Eigenschaft nützlich, etwa wenn eine Formularprüfung oder ein Stapelimport mehrere Fehler sammeln und gemeinsam melden soll, statt beim ersten Fehler abzubrechen. Der Aufrufer fängt dann einen einzigen Fehler ab und kann über errors jeden Einzelfehler auswerten.

errors ist eine eigene Eigenschaft der Instanz und liegt nicht auf dem Prototyp. Sie ist beschreibbar (writable) und konfigurierbar (configurable), aber nicht aufzählbar (non-enumerable).

Rückgabewert

Typ

Array<any>

Beschreibung

Ein Array mit den gesammelten Fehlern. Die Elemente sind meist Error-Objekte, können aber beliebige Werte sein, z. B. Strings oder undefined, weil Promises mit jedem Wert abgelehnt werden können.

Beispiele

AggregateError erzeugen und errors auslesen

const fehler = new AggregateError(
  [new TypeError('Ungültiger Typ'), new RangeError('Wert zu groß')],
  'Mehrere Fehler aufgetreten'
);

console.log(fehler.message);
console.log(fehler.errors.length);
fehler.errors.forEach((e) => console.log(`${e.name}: ${e.message}`));

Mehrere Fehler aufgetreten 2 TypeError: Ungültiger Typ RangeError: Wert zu groß

Promise.any: alle Quellen fehlgeschlagen

const ladeVon = (url, ms) =>
  new Promise((_, reject) =>
    setTimeout(() => reject(new Error(`${url} nicht erreichbar`)), ms)
  );

const main = async () => {
  try {
    await Promise.any([
      ladeVon('cdn1.example.com', 300),
      ladeVon('cdn2.example.com', 100),
      ladeVon('cdn3.example.com', 200),
    ]);
  } catch (err) {
    if (err instanceof AggregateError) {
      // Reihenfolge entspricht den Eingabe-Promises, nicht dem Zeitpunkt der Ablehnung
      err.errors.forEach((e, i) => console.log(i, e.message));
    }
  }
};

main();

0 cdn1.example.com nicht erreichbar 1 cdn2.example.com nicht erreichbar 2 cdn3.example.com nicht erreichbar

Validierungsfehler sammeln und gemeinsam melden

const validiereNutzer = ({ name, email, alter }) => {
  const probleme = [];
  if (!name) probleme.push(new Error('Name fehlt'));
  if (!email?.includes('@')) probleme.push(new Error('E-Mail ungültig'));
  if (!(alter >= 18)) probleme.push(new RangeError('Mindestalter 18'));
  if (probleme.length) {
    throw new AggregateError(probleme, 'Validierung fehlgeschlagen');
  }
  return true;
};

try {
  validiereNutzer({ name: '', email: 'test', alter: 16 });
} catch (err) {
  const meldungen = err.errors.map((e) => e.message);
  console.log(meldungen);
}

[ 'Name fehlt', 'E-Mail ungültig', 'Mindestalter 18' ]

errors ist eine Kopie und nicht aufzählbar

const quelle = [new Error('A')];
const agg = new AggregateError(quelle);

quelle.push(new Error('B'));
console.log(agg.errors.length);   // Kopie: bleibt 1
console.log(Object.keys(agg));    // errors ist nicht aufzählbar
console.log(JSON.stringify(agg)); // taucht in JSON nicht auf
console.log(Object.hasOwn(agg, 'errors'));

1 [] {} true

// Wichtig · Fallstricke

Kopie statt Referenz: Der Konstruktor kopiert das übergebene Iterable in ein neues Array. Spätere Änderungen am Quell-Array wirken sich nicht auf errors aus.
Nicht aufzählbar: JSON.stringify(), Object.keys() und der Spread-Operator ({...err}) übernehmen errors nicht. Für Logging oder die Übertragung an einen Server musst du die Eigenschaft ausdrücklich auslesen, z. B. mit err.errors.map(e => e.message).
Beliebige Werte: Die Elemente müssen keine Error-Objekte sein. Prüfe vor dem Zugriff auf .message am besten mit e instanceof Error.
Leeres Array: Promise.any([]) lehnt sofort mit einem AggregateError ab, dessen errors leer ist.
Pflichtargument: new AggregateError() ohne Iterable wirft einen TypeError, weil undefined nicht iterierbar ist.
Kompatibilität: Verfügbar ab ES2021 (Chrome 85, Firefox 79, Safari 14, Node.js 15). Für ältere Umgebungen gibt es Polyfills, z. B. core-js.

Siehe auch

Promise.any() Error Error.prototype.cause try...catch SuppressedError: error