Error.stackTraceLimit — Eigenschaft · JavaScript-Referenz

Signatur

Error.stackTraceLimit

Beschreibung

Error.stackTraceLimit ist eine nicht standardisierte statische Dateneigenschaft des Error-Konstruktors. Sie gibt an, wie viele Aufruf-Frames die Engine beim Erzeugen eines Fehlerobjekts höchstens in dessen stack-Text schreibt. In V8 (Chrome, Node.js, Deno) liegt der Standardwert bei 10, in Firefox bei 128.

Nützlich ist die Eigenschaft vor allem beim Debuggen tiefer Aufrufketten: Bei Rekursion, vielen Middleware-Schichten oder großen Frameworks wird der eigentlich interessante Frame oft abgeschnitten. Setzt du den Wert höher (oder auf Infinity), bekommst du den vollständigen Stack. Umgekehrt kannst du den Wert auf 0 setzen, um das Erfassen von Stacks ganz abzuschalten, zum Beispiel für Fehler, die nur zur Steuerung des Programmablaufs dienen und bei denen die Kosten fürs Erfassen stören.

Der Wert wird zum Zeitpunkt der Fehlererzeugung gelesen (bei new Error() bzw. Error.captureStackTrace()). Eine spätere Änderung wirkt sich nicht auf bereits erzeugte Fehlerobjekte aus. Ist der Wert keine Zahl (z. B. nach delete Error.stackTraceLimit), erfasst V8 gar keinen Stack mehr.

Rückgabewert

Typ

number

Beschreibung

Die aktuell eingestellte maximale Anzahl von Stack-Frames (nicht negative Ganzzahl oder Infinity). Standard: 10 in V8, 128 in Firefox. Die Eigenschaft ist beschreibbar und konfigurierbar.

Beispiele

Standardwert auslesen und Wirkung zeigen

console.log(Error.stackTraceLimit);

const tief = (n) => {
  if (n === 0) throw new Error('Boden erreicht');
  return tief(n - 1);
};

try {
  tief(50);
} catch (err) {
  // Zeilen, die mit "at " beginnen, zählen (V8-Format)
  const frames = err.stack.split('\n').filter((z) => z.trim().startsWith('at '));
  console.log(frames.length);
}

10 10

Vollständigen Stack beim Debuggen erzwingen (Node.js)

// Ganz am Anfang des Einstiegsskripts, z. B. nur in der Entwicklung
if (process.env.NODE_ENV !== 'production') {
  Error.stackTraceLimit = Infinity;
}

const rekursion = (n) => (n === 0 ? new Error('tief') : rekursion(n - 1));
const err = rekursion(30);
console.log(err.stack.split('\n').length > 30);

true

Stack-Erfassung temporär abschalten und Wert wiederherstellen

const ohneStack = (nachricht) => {
  const vorher = Error.stackTraceLimit;
  Error.stackTraceLimit = 0;
  try {
    return new Error(nachricht);
  } finally {
    Error.stackTraceLimit = vorher; // globalen Zustand nicht verschmutzen
  }
};

const e = ohneStack('Abbruch');
console.log(e.stack);

Error: Abbruch

Auf Unterstützung prüfen

const unterstuetzt = typeof Error.stackTraceLimit === 'number';
console.log(unterstuetzt ? `Limit: ${Error.stackTraceLimit}` : 'Nicht unterstützt');

Limit: 10

// Wichtig · Fallstricke

Nicht standardisiert: Die Eigenschaft steht nicht in der ECMAScript-Spezifikation. V8 unterstützt sie seit Langem, Firefox erst ab Version 128. Das stack-Format selbst ist ebenfalls je nach Engine anders. Verlass dich in portablem Code nicht darauf und prüfe vorher mit typeof Error.stackTraceLimit === 'number'.
Globaler Zustand: Die Änderung gilt für alle Fehler im ganzen Realm (auch für die in Bibliotheken). Stelle den alten Wert wieder her, wenn du ihn nur vorübergehend änderst.
Performance: Hohe Werte oder Infinity machen das Erzeugen von Fehlern teurer und verbrauchen mehr Speicher. Für Produktionscode mit vielen geworfenen Fehlern ist das nicht zu empfehlen.
Kein rückwirkender Effekt: Bereits erzeugte Fehlerobjekte behalten ihren Stack. Der Wert wird nur beim Erzeugen gelesen.
In V8 gilt: Ist der Wert keine Zahl oder wurde die Eigenschaft gelöscht, wird gar kein Stack erfasst. err.stack enthält dann nur noch die Kopfzeile oder ist undefined.
In Node.js lässt sich das Limit auch über das CLI-Flag --stack-trace-limit=50 setzen.

Siehe auch

Error Error.prototype.stack Error.captureStackTrace() throw try...catch