ErrorEvent.filename — Eigenschaft · JavaScript-Referenz

Signatur

ErrorEvent.filename

Beschreibung

Die Eigenschaft filename des ErrorEvent-Interfaces enthält die URL der Skriptdatei, in der ein nicht abgefangener Laufzeitfehler ausgelöst wurde, zum Beispiel "https://example.com/js/app.js". Bei Inline-Skripten steht dort meist die URL des HTML-Dokuments. Die Eigenschaft ist schreibgeschützt und wird beim Erzeugen des Events gesetzt.

Gebraucht wird filename vor allem beim globalen Fehler-Logging: Ein Listener auf window.addEventListener("error", …) oder auf dem error-Event eines Worker kann zusammen mit lineno, colno und message die genaue Fehlerstelle an einen Monitoring-Dienst schicken.

Gibt es keine Dateiinformation, etwa bei Code aus eval() oder bei Fehlern aus fremden Ursprüngen ohne CORS-Freigabe, ist der Wert ein leerer String "". Bei selbst erzeugten Events mit new ErrorEvent() kann der Wert über das Options-Objekt gesetzt werden, sonst ist er standardmäßig "".

Rückgabewert

Typ

string

Beschreibung

Die URL bzw. der Dateiname des Skripts, in dem der Fehler auftrat, oder ein leerer String "", wenn diese Angabe fehlt oder verborgen wird.

Beispiele

Globalen Fehler mit Dateiangabe protokollieren

window.addEventListener("error", (event) => {
  // Nur Laufzeitfehler aus Skripten, keine Ladefehler von Ressourcen
  if (!(event instanceof ErrorEvent)) return;
  console.log(`Fehler in ${event.filename || "(unbekannt)"}:${event.lineno}:${event.colno}`);
  console.log("Meldung:", event.message);
});

// Absichtlich einen Fehler auslösen
setTimeout(() => {
  undefinedFunction();
}, 0);

Fehler in https://example.com/js/app.js:9:3 Meldung: Uncaught ReferenceError: undefinedFunction is not defined

Fehlerbericht an einen Monitoring-Endpunkt senden

const reportError = (event) => {
  const payload = {
    message: event.message,
    file: event.filename,
    line: event.lineno,
    column: event.colno,
    stack: event.error?.stack ?? null,
    page: location.href,
  };
  // sendBeacon funktioniert auch beim Verlassen der Seite
  navigator.sendBeacon("/api/errors", JSON.stringify(payload));
};

window.addEventListener("error", reportError);

Fehler in einem Web Worker lokalisieren

const worker = new Worker("rechner.js");

worker.onerror = (event) => {
  event.preventDefault(); // Standardausgabe in der Konsole unterdrücken
  console.warn(`Worker-Fehler in ${event.filename}, Zeile ${event.lineno}: ${event.message}`);
};

Worker-Fehler in https://example.com/rechner.js, Zeile 12: Uncaught TypeError: x is not a function

ErrorEvent selbst erzeugen

const ev = new ErrorEvent("error", {
  message: "Konfiguration ungültig",
  filename: "config-loader.js",
  lineno: 42,
  colno: 7,
});

console.log(ev.filename);
console.log(new ErrorEvent("error").filename === "");

config-loader.js true

// Wichtig · Fallstricke

Fremde Ursprünge: Bei Fehlern aus Skripten einer anderen Domain ohne crossorigin-Attribut und passenden CORS-Header (Access-Control-Allow-Origin) verbirgt der Browser die Details. Dann ist message nur "Script error.", filename ist "" und lineno/colno sind 0. Abhilfe: <script src="…" crossorigin="anonymous"> plus CORS-Header auf dem CDN.
Ladefehler von Ressourcen: Scheitert das Laden von <img>, <script> o. ä., wird ein einfaches Event ausgelöst und kein ErrorEvent. Dann gibt es kein filename. Um diese Events auf window abzufangen, braucht der Listener die Capture-Phase (addEventListener("error", fn, true)).
window.onerror: Der Handler window.onerror bekommt statt des Event-Objekts die Argumente (message, source, lineno, colno, error). Dort entspricht source dem Wert von filename.
Minifizierter Code: filename verweist auf die ausgelieferte, gebündelte Datei. Die ursprüngliche Quelldatei erhält man nur über Source Maps.
Datenschutz: Die URL kann Query-Parameter mit Tokens oder Sitzungs-IDs enthalten. Sie sollte vor dem Versand an Logging-Dienste bereinigt werden.
Die Eigenschaft funktioniert in allen modernen Browsern, in Web Workers und in Service Workers.

Siehe auch

ErrorEvent.lineno ErrorEvent.colno ErrorEvent.message ErrorEvent.error BlobEvent.timecode