new ReferenceError() — Methode · JavaScript-Referenz

Signatur

new ReferenceError(message, options)

Beschreibung

Der Konstruktor ReferenceError() erzeugt ein Fehlerobjekt vom Typ ReferenceError, einer Unterklasse von Error. Die JavaScript-Engine wirft solche Fehler selbst, wenn Code auf einen nicht deklarierten Bezeichner zugreift (z. B. undefinedVar) oder wenn eine let-/const-Variable in der Temporal Dead Zone vor ihrer Initialisierung gelesen wird.

Selbst erzeugt man einen ReferenceError vor allem in Interpretern, Template-Engines, Konfigurations-Resolvern oder Sandbox-Umgebungen. Dort bildet er dieselbe Bedeutung nach: Ein Name, auf den verwiesen wird, kann nicht aufgelöst werden. So können aufrufende Stellen den Fehler mit instanceof ReferenceError gezielt unterscheiden.

Der Konstruktor lässt sich mit oder ohne new aufrufen, das Ergebnis ist identisch. Seit ES2022 nimmt er als zweites Argument ein Objekt options entgegen. Dessen Eigenschaft cause hält die ursprüngliche Fehlerursache fest, sodass sich Fehler sauber verketten lassen.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Menschenlesbare Beschreibung des Fehlers. Sie wird in einen String umgewandelt und in `error.message` gespeichert.
$options	{ cause?: any }		Objekt mit der optionalen Eigenschaft `cause`. Sie gibt die ursprüngliche Ursache an und landet in `error.cause` (ES2022).

Rückgabewert

Typ

ReferenceError

Beschreibung

Eine neue ReferenceError-Instanz mit name === "ReferenceError", der übergebenen message, gegebenenfalls cause und einem von der Engine abhängigen stack.

Beispiele

ReferenceError erzeugen und untersuchen

const err = new ReferenceError('Variable "total" ist nicht definiert');

console.log(err instanceof ReferenceError); // true
console.log(err instanceof Error);          // true
console.log(err.name);
console.log(err.message);

true true ReferenceError Variable "total" ist nicht definiert

Von der Engine geworfenen ReferenceError abfangen

try {
  // Zugriff vor der Initialisierung (Temporal Dead Zone)
  console.log(price);
  const price = 42;
} catch (e) {
  if (e instanceof ReferenceError) {
    console.log(`${e.name}: ${e.message}`);
  }
}

ReferenceError: Cannot access 'price' before initialization

Platzhalter in einer Mini-Template-Engine auflösen

const render = (template, vars) =>
  template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
    if (!Object.hasOwn(vars, key)) {
      throw new ReferenceError(`Unbekannter Platzhalter: ${key}`);
    }
    return String(vars[key]);
  });

try {
  console.log(render('Hallo {{name}}!', { name: 'Anna' }));
  console.log(render('Preis: {{preis}}', {}));
} catch (e) {
  console.error(e.name, '-', e.message);
}

Hallo Anna! ReferenceError - Unbekannter Platzhalter: preis

Fehler verketten mit options.cause

const config = new Map([['apiUrl', 'https://api.example.com']]);

const resolve = (key) => {
  try {
    if (!config.has(key)) throw new Error(`Schlüssel fehlt: ${key}`);
    return config.get(key);
  } catch (original) {
    throw new ReferenceError(`Konfiguration "${key}" nicht auflösbar`, { cause: original });
  }
};

try {
  resolve('timeout');
} catch (e) {
  console.log(e.message);
  console.log('Ursache:', e.cause.message);
}

Konfiguration "timeout" nicht auflösbar Ursache: Schlüssel fehlt: timeout

// Wichtig · Fallstricke

Wortlaut der Meldungen: Die Texte, die die Engine selbst erzeugt, unterscheiden sich je nach Engine. V8 meldet z. B. x is not defined, SpiderMonkey x is not defined bzw. can't access lexical declaration 'x' before initialization. Werten Sie deshalb nie message aus, sondern prüfen Sie den Typ mit instanceof.
typeof wirft keinen Fehler: typeof nichtDeklariert liefert "undefined" statt eines ReferenceError. Das gilt nicht in der Temporal Dead Zone: Dort wirft auch typeof.
Strict Mode: Wenn Sie einer nicht deklarierten Variablen einen Wert zuweisen, wird im Sloppy Mode stillschweigend eine globale Variable angelegt. Im Strict Mode wirft dieselbe Zuweisung einen ReferenceError.
Unterschied zu anderen Fehlern: Ist die Variable zwar vorhanden, hat aber den Wert undefined, und Sie greifen auf eine ihrer Eigenschaften zu, entsteht ein TypeError und kein ReferenceError. Eine ungültige Zuweisung wie 1 = x ist heute ein SyntaxError.
options.cause wird erst ab ES2022 unterstützt (Chrome 93, Firefox 91, Safari 15, Node.js 16.9). Ältere Umgebungen ignorieren das Argument.
stack ist nicht standardisiert, wird aber von allen gängigen Engines bereitgestellt.

Siehe auch

Error new Error() Error.prototype.cause try...catch throw