Error: fileName — Eigenschaft · JavaScript-Referenz

Signatur

Error.prototype.fileName

Beschreibung

Die Daten-Eigenschaft fileName ist eine Firefox-spezifische Erweiterung von Error-Instanzen. Sie enthält die URL oder den Pfad des Skripts, in dem das Fehlerobjekt erzeugt wurde. Das ist die Stelle, an der new Error() aufgerufen wurde, und nicht unbedingt die Stelle, an der der Fehler mit throw geworfen wird. Zusammen mit lineNumber und columnNumber lässt sich so die Herkunft eines Fehlers genauer bestimmen.

Es handelt sich um eine eigene, beschreibbare Eigenschaft der Instanz. Dem Konstruktor kann man in Firefox den Dateinamen als zweites Argument mitgeben: new Error(message, fileName, lineNumber). In anderen Engines wird dieses zweite Argument als options-Objekt (z. B. { cause }) gelesen und fileName nicht gesetzt.

Gebraucht wird die Eigenschaft vor allem beim Protokollieren und Auswerten von Fehlern, etwa in einem eigenen Fehler-Reporter. Im produktiven, browserübergreifenden Code sollte man sich nicht darauf verlassen. Portabler sind error.stack (ebenfalls nicht standardisiert, aber in allen großen Engines vorhanden) und beim globalen error-Event die Eigenschaft ErrorEvent.filename.

Rückgabewert

Typ

string | undefined

Beschreibung

In Firefox die URL bzw. der Pfad der Datei, in der der Fehler erzeugt wurde, z. B. "https://example.com/app.js". In Chrome, Safari, Node.js und Deno ist der Wert undefined, außer er wurde selbst zugewiesen.

Beispiele

Dateinamen eines Fehlers auslesen (Firefox)

try {
  JSON.parse('{ungültig}');
} catch (err) {
  // In Firefox: URL des Skripts, in anderen Browsern undefined
  console.log(err.fileName);
  console.log(err.lineNumber);
}

https://example.com/js/app.js 2

Browserübergreifender Fehler-Reporter mit Fallback

const getErrorLocation = (err) => {
  if (typeof err.fileName === 'string') {
    return { file: err.fileName, line: err.lineNumber ?? null };
  }
  // Fallback: erste Stack-Zeile mit URL auswerten
  const match = err.stack?.match(/(https?:\/\/[^\s)]+):(\d+):(\d+)/);
  return match
    ? { file: match[1], line: Number(match[2]) }
    : { file: 'unbekannt', line: null };
};

try {
  undefinedFunction();
} catch (err) {
  console.log(getErrorLocation(err));
}

{ file: 'https://example.com/js/app.js', line: 17 }

fileName manuell setzen (eigene Fehlerklasse)

class ConfigError extends Error {
  constructor(message, file) {
    super(message);
    this.name = 'ConfigError';
    // eigene Eigenschaft funktioniert in jeder Engine
    this.fileName = file;
  }
}

const err = new ConfigError('Schlüssel "port" fehlt', 'config/server.json');
console.log(`${err.name} in ${err.fileName}: ${err.message}`);

ConfigError in config/server.json: Schlüssel "port" fehlt

Globale Fehler über ErrorEvent.filename erfassen

const onError = (event) => {
  // ErrorEvent.filename ist standardisiert und in allen Browsern verfügbar
  console.log(`Fehler in ${event.filename}:${event.lineno}`, event.message);
};

window.addEventListener('error', onError);
// später wieder entfernen:
// window.removeEventListener('error', onError);

Fehler in https://example.com/js/app.js:42 Uncaught TypeError: x is not a function

// Wichtig · Fallstricke

Nicht standardisiert: fileName gibt es nur in Firefox (SpiderMonkey). V8 (Chrome, Edge, Node.js) und JavaScriptCore (Safari) liefern undefined. Für Code in Produktion nicht geeignet.
Der Wert beschreibt die Stelle, an der das Fehlerobjekt erzeugt wurde, nicht die Stelle des throw. Wenn Fehler in Hilfsfunktionen gebaut werden, zeigt fileName deshalb auf die Datei der Hilfsfunktion.
Die Eigenschaft ist beschreibbar und lässt sich daher leicht überschreiben. Für sicherheitsrelevante Entscheidungen taugt sie nicht.
Das Konstruktor-Argument new Error(msg, fileName) ist ebenfalls Firefox-spezifisch. Seit ES2022 steht an dieser Position das options-Objekt ({ cause }). Einen String als zweites Argument übergeben andere Engines deshalb stillschweigend.
Bei gebündeltem oder minifiziertem Code zeigt fileName auf das Bundle und nicht auf die Quelldatei. Die ursprüngliche Datei findet man nur über Source Maps.
Bei Skripten von einer fremden Origin, die ohne CORS-Header (crossorigin-Attribut) geladen werden, verbergen Browser im globalen error-Event Details wie den Dateinamen. Die Meldung lautet dann nur „Script error.“.

Siehe auch

Error Error.prototype.stack ErrorEvent.filename Error: lineNumber Error: message