Signatur
Beschreibung
ReferenceError ist eine eingebaute Fehlerklasse in JavaScript, die automatisch von der JavaScript-Engine geworfen wird, wenn Code auf einen Bezeichner (Variable, Funktion, Konstante) zugreift, der im aktuellen Gültigkeitsbereich nicht deklariert wurde. Typische Ursachen sind Tippfehler in Variablennamen, das Verwenden von Variablen vor ihrer Deklaration (sog. Temporal Dead Zone bei let und const) oder das Zugreifen auf globale Variablen, die in einem anderen Kontext existieren.
ReferenceError erbt von Error und bringt die üblichen Eigenschaften name, message und stack mit. Man kann eigene ReferenceError-Instanzen mit new ReferenceError(message) erzeugen und mit throw werfen, wenn man in eigenen Bibliotheken oder APIs klar kommunizieren möchte, dass ein unbekannter Bezeichner übergeben wurde.
Besonders wichtig ist der Unterschied zur Temporal Dead Zone: Variablen, die mit let oder const deklariert werden, existieren zwar im Gültigkeitsbereich, können aber vor ihrer Deklarationszeile nicht gelesen werden – auch das führt zu einem ReferenceError. Im Gegensatz dazu werden mit var deklarierte Variablen ge-hoisted und liefern stattdessen undefined.
- Zugriff auf nicht deklarierte Variablen →
ReferenceError - Zugriff auf
let/constvor Deklaration →ReferenceError(Temporal Dead Zone) - Zugriff auf
varvor Deklaration →undefined(kein Fehler)
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $message | string | "" | Optionale, menschenlesbare Fehlerbeschreibung, die in error.message gespeichert wird. |
| $options | object | Optionales Optionsobjekt. Kann die Eigenschaft cause enthalten, um den ursprünglichen Fehler als Ursache zu hinterlegen (z. B. { cause: originalError }). Seit ES2022. |
Rückgabewert
ReferenceError-Instanz zurück. Die Eigenschaft name ist dabei automatisch auf "ReferenceError" gesetzt.Beispiele
Automatisch geworfener ReferenceError
try {
console.log(nichtDeklariertVariable);
} catch (err) {
console.log(err instanceof ReferenceError); // true
console.log(err.name); // "ReferenceError"
console.log(err.message); // "nichtDeklariertVariable is not defined"
}Temporal Dead Zone bei let/const
try {
console.log(wert); // Zugriff VOR der Deklaration
const wert = 42;
} catch (err) {
console.log(err instanceof ReferenceError); // true
console.log(err.message); // "Cannot access 'wert' before initialization"
}Eigenen ReferenceError werfen und cause nutzen
function getConfig(key, config) {
if (!(key in config)) {
throw new ReferenceError(
`Konfigurationsschlüssel "${key}" ist nicht definiert.`,
{ cause: new Error(`Verfügbare Schlüssel: ${Object.keys(config).join(", ")}`) }
);
}
return config[key];
}
try {
const config = { host: "localhost", port: 3000 };
getConfig("timeout", config);
} catch (err) {
console.log(err.message);
console.log(err.cause?.message);
}// Wichtig · Fallstricke
Temporal Dead Zone (TDZ): Der Bereich zwischen dem Anfang eines Blocks und der eigentlichen Deklaration von let/const heißt Temporal Dead Zone. Jeder Lesezugriff auf die Variable in dieser Zone führt zu einem ReferenceError, obwohl die Variable technisch im Scope existiert. Das ist ein häufiger Stolperstein beim Refactoring von var-Code auf let/const.
Strict Mode: Im Strict Mode ('use strict') löst das Zuweisen an eine nicht deklarierte Variable ebenfalls einen ReferenceError aus. Im Nicht-Strict-Mode würde dieselbe Zuweisung stillschweigend eine globale Variable erzeugen.
Browser-Kompatibilität: ReferenceError sowie die cause-Option sind in allen modernen Browsern und Node.js unterstützt. cause erfordert mindestens Node.js 16.9+ bzw. aktuelle Browser-Versionen (Baseline 2022).