new Error() — Methode · JavaScript-Referenz

Signatur

new Error(message, options)

Beschreibung

Mit new Error() erzeugt man ein Fehlerobjekt, das man meist direkt mit throw auslöst. Das Objekt hat die Eigenschaften message und name (standardmäßig "Error"). In allen gängigen Umgebungen kommt außerdem die nicht standardisierte, aber weit unterstützte Eigenschaft stack mit dem Aufrufstapel hinzu, der beim Erzeugen des Objekts festgehalten wird.

Seit ES2022 kann man als zweites Argument ein Optionsobjekt mit der Eigenschaft cause übergeben. Damit lassen sich Fehler verketten: Ein technischer Fehler auf niedriger Ebene (z. B. ein Netzwerkfehler) wird in einen aussagekräftigeren Fehler der Anwendung eingepackt, ohne dass die ursprüngliche Information verloren geht.

Error kann auch ohne new aufgerufen werden – Error("x") verhält sich genauso wie new Error("x"). Für eigene Fehlertypen leitet man mit class MyError extends Error ab. Für bestimmte Fälle gibt es schon eingebaute Unterklassen wie TypeError, RangeError oder SyntaxError.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Lesbare Beschreibung des Fehlers. Andere Werte als Strings werden mit `String()` umgewandelt. Wird nichts übergeben, bekommt die Instanz keine eigene `message`-Eigenschaft; es gilt dann der leere String vom Prototyp.
$options	{ cause?: any }		Optionsobjekt. `cause` gibt die ursprüngliche Ursache des Fehlers an und wird als Eigenschaft `error.cause` übernommen. Das kann ein beliebiger Wert sein, meist ist es ein anderes `Error`-Objekt.

Rückgabewert

Typ

Error

Beschreibung

Ein neues Error-Objekt mit den Eigenschaften message, name, gegebenenfalls cause und meist auch stack.

Beispiele

Einfachen Fehler erzeugen und abfangen

const teile = (a, b) => {
  if (b === 0) {
    throw new Error('Division durch null ist nicht erlaubt');
  }
  return a / b;
};

try {
  teile(10, 0);
} catch (err) {
  console.log(err.name);
  console.log(err.message);
  console.log(err instanceof Error);
}

Error Division durch null ist nicht erlaubt true

Fehler verketten mit cause (ES2022)

const ladeBenutzer = async (id) => {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } catch (err) {
    throw new Error(`Benutzer ${id} konnte nicht geladen werden`, { cause: err });
  }
};

try {
  await ladeBenutzer(42);
} catch (err) {
  console.log(err.message);
  console.log('Ursache:', err.cause?.message);
}

Benutzer 42 konnte nicht geladen werden Ursache: HTTP 404

Eigene Fehlerklasse ableiten

class ValidationError extends Error {
  constructor(field, message, options) {
    super(message, options);
    this.name = 'ValidationError';
    this.field = field;
  }
}

const pruefeAlter = (alter) => {
  if (!Number.isInteger(alter) || alter < 0) {
    throw new ValidationError('alter', `Ungültiges Alter: ${alter}`);
  }
  return alter;
};

try {
  pruefeAlter(-3);
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(`${err.name} [${err.field}]: ${err.message}`);
  }
}

ValidationError [alter]: Ungültiges Alter: -3

Aufruf ohne new und toString()

const e = Error('Etwas ging schief');
console.log(e instanceof Error);
console.log(String(e));
console.log(new Error().message === '');

true Error: Etwas ging schief true

// Wichtig · Fallstricke

Nur Fehlerobjekte werfen: throw 'Text' funktioniert zwar, liefert aber weder stack noch instanceof Error. Werfen Sie immer Error-Instanzen.
stack ist nicht standardisiert: Aufbau und Inhalt unterscheiden sich zwischen V8 (Chrome, Node.js), SpiderMonkey (Firefox) und JavaScriptCore (Safari). Werten Sie den Stack nicht maschinell aus. In V8 kann Error.captureStackTrace() den Stack gezielt anpassen.
cause: Wird in Chrome 93+, Firefox 91+, Safari 15+ und Node.js 16.9+ unterstützt. Ältere Umgebungen ignorieren das Optionsobjekt stillschweigend.
Unterklassen: Setzen Sie in eigenen Fehlerklassen this.name, sonst meldet sich der Fehler als "Error". Beim Transpilieren nach ES5 kann instanceof ohne Object.setPrototypeOf(this, new.target.prototype) fehlschlagen.
Serialisierung: JSON.stringify(new Error('x')) ergibt {}, weil message und stack nicht aufzählbar sind. Übertragen Sie die Felder daher einzeln oder nutzen Sie structuredClone().
Sicherheit: Geben Sie Stack-Traces und interne Fehlermeldungen nicht ungefiltert an Endnutzer oder API-Clients weiter. Sie können Pfade, Code-Aufbau oder sensible Daten preisgeben.

Siehe auch

Error Error.prototype.stack throw try...catch TypeError AggregateError