#Error option limit S1

#ECMAScript Proposal: Error option limit

#Status

Champion: Ruben Bridgewater

Author: Ruben Bridgewater ruben@bridgewater.de

Stage: 1

#Overview

This proposal introduces a new per-error Error options property, limit, that specifies the maximum number of implementation defined stack frames to capture for that specific error instance.

• limit is a numeric option interpreted using ToIntegerOrInfinity.
• If provided, the local limit overrides any global stack trace limit (e.g., V8's Error.stackTraceLimit) for that error only.
• Negative values throw a RangeError; limit must be a non-negative integer, undefined, or Infinity.
• Conceptually, this behaves like temporarily setting the V8 specific Error.stackTraceLimit immediately before creating the error and restoring it right after, but without any global side effects.

This provides a standardized, cross-engine way to control stack depth per error instance and avoids manipulating a global knob that affects unrelated errors.

#Proposed API

new Error(message, { limit: 3 })
new TypeError(message, { limit: 0 })
new RangeError(message, { limit: 50 })
new AggregateError(iterable, message, { limit: Infinity })
// ... applies to all built-in Error constructors that accept an options bag

#Validation

• If options is provided and has a limit property whose value is not undefined, the engine computes n = ToIntegerOrInfinity(limit).
  • If n < 0, throw a RangeError.
  • Otherwise, record n on the error instance.
• If limit is undefined or absent, the default behavior is unchanged (the global limit, if any, applies).

#Rationale: a local limit is more intuitive

• The global Error.stackTraceLimit defined in V8 is coarse-grained and impacts all errors, including those that do not need deeper stacks.
• A per-error limit expresses intent exactly where it matters and avoids surprising global side effects.
• The local limit always overrides the global limit for that specific error instance, which matches developer expectations when tailoring diagnostics.
• Eliminates boilerplate patterns that temporarily modify the global Error.stackTraceLimit just to construct one error.

#Why the global Error.stackTraceLimit defined in V8 is error-prone

• Changes are process-wide and time-based, so unrelated errors can inherit the wrong limit.
• Code between “set” and “reset” can throw synchronously, skipping the reset.
• Asynchronous boundaries make it easy to affect other in-flight work during await.
• People sometimes simply forget to reset the global knob.

Examples:

1. Synchronous throw during error creation skips reset

// Global mutation that never resets if message coercion throws
const prev = Error.stackTraceLimit;
Error.stackTraceLimit = 2;

// toString can throw during Error(message) coercion
const msg = { toString() { throw new TypeError('format failed'); } };
new Error(msg); // throws before any reset runs; global now stuck at 2

With a local limit, there’s no global mutation:

throw new Error('boom', { limit: 2 });

1. Asynchronous hazard: unrelated errors use your temporary limit

async function makeErrorLater() {
  const prev = Error.stackTraceLimit;
  Error.stackTraceLimit = Infinity; // intend: deep trace for this one error

  // Meanwhile, other tasks executing during this await will also see Infinity.
  await doWorkElsewhere();

  const err = new Error('x'); // gets deep trace...
  Error.stackTraceLimit = prev; // ...but other errors during await did too.
}

With a local limit, only the intended error is affected:

async function makeErrorLater() {
  await doWorkElsewhere();
  throw new Error('x', { limit: Infinity });
}

1. Simple omission: forgetting to reset

Error.stackTraceLimit = 1;
// ... time passes, code evolves ...
// reset was forgotten; all subsequent errors now have too-short stacks

Per-error limit avoids this entire class of mistakes.

#Use cases

• Performance-sensitive hot paths where only the first few frames are needed (e.g., limit: 2) to minimize overhead.
• Focused deep debugging for specific error types or code paths (e.g., limit: 100 or Infinity) without changing behavior for other errors.
• Library and framework utilities that want predictable stack depth for their own diagnostic errors without affecting user code globally.

#In the wild (prior art)

Developers frequently simulate per-error control by temporarily changing the global Error.stackTraceLimit before creating an error and resetting it afterward. Examples and references:

• MDN: Error.stackTraceLimit (documents temporary adjustment patterns) — https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stackTraceLimit
• Node.js documentation: Errors — https://nodejs.org/api/errors.html
• GitHub code search: “Error.stackTraceLimit = Infinity” — https://github.com/search?q=%22Error.stackTraceLimit+%3D+Infinity%22&type=code
• longjohn (async stack tracing) sets very high/Infinity limits — https://github.com/mattinsler/longjohn
• Mocha full trace option (ecosystem precedent for “full stacks”) — https://mochajs.org/#--full-trace

These demonstrate that developers already rely on per-error or context-local stack depth control; standardizing a per-error limit removes the need for global mutations.

#Semantics

• Let L be the recorded limit for the error instance, if provided; otherwise undefined.
• When the host captures the stack for the error:
  • If L is undefined, apply the host’s default/global stack trace limit.
  • Otherwise, apply L as the limit for this error only.
• Formatting and any other host-defined stack processing are unchanged.

A stack frame is implementation defined.

#Specification text (outline)

1. In each Error (and subclass) constructor that accepts an options argument:
   • Let options be the second (or third, for AggregateError) argument.
   • If options is not undefined:
     • Let limit be ? Get(options, "limit").
     • If limit is not undefined:
       • Let n be ? ToIntegerOrInfinity(limit).
       • If n < 0, throw a RangeError.
       • Record n on the error instance in an internal slot for later use during stack capture.
2. When capturing the stack for an error instance E:
   • Let S be the sequence of frames that would be captured for E absent this option.
   • Let n be E.[[StackTraceLimitOverride]], if present; otherwise undefined.
   • Apply the stack length limit:
     • If n is undefined, apply the host’s global/default limit.
     • Otherwise, apply n to S.
   • Produce the stack string from S as usual.

See the full spec draft:

• spec.emu

#Non-goals and edge cases

• This proposal does not standardize stack string formatting, source map application, or async stack joining.
• If limit is 0, no frames are included for the error beyond the error header (implementation defined).
• The option is per-error and does not affect other errors or future stack captures.

#Alternatives considered

• Continue using global Error.stackTraceLimit. Rejected for lack of precision, surprising global side effects, and boilerplate required to simulate per-error control.
• Add new host-specific APIs. Rejected; standardizing a language option is more portable and interoperable.

#Conclusion

limit provides an explicit, local way to control stack depth per error, matching developer expectations, improving ergonomics, and avoiding global side effects while aligning with ecosystem practice.