Error.captureStackTrace() adds a stack property to an object you pass in. The stack is a piece of text. Its first line is the name and message of the object, and the lines after it list the functions that were running when you made the call.
It comes from the V8 engine (Chrome, Edge, Node.js) and is not part of the official JavaScript standard. You mostly use it in custom errors, to make the stack start at the code that caused the problem instead of at your own helper function or constructor.
Remember
Error.captureStackTrace(target);
Error.captureStackTrace(target, fn);
target → gets a "stack" property (a string)
fn → this function (and what it called) is hidden
returns → undefined (it changes target, nothing more)
Set name and message first.
They become the first line of the stack.
Syntax
Pass the object that should receive the stack. Add a second argument when you want to hide one function from the top of the stack.
Adds obj.stack. The stack starts at the function that made this call.
Error.captureStackTrace(obj, fn)
Same, but fn is left out. The stack starts at the function that called fn.
typeof Error.captureStackTrace === "function"
Check that the method exists before you use it, because not every JavaScript engine has it.
A non-standard V8 method; no import required, but check that it exists before you call it. Siblings: Error.isError() and toString().
Library declarations
JavaScript
// V8 API (non-standard)
Error.captureStackTrace(targetObject)
Error.captureStackTrace(targetObject, constructorOpt)
// returns undefined
// related setting: Error.stackTraceLimit (V8 default: 10 lines)
Parameters
Parameter
Description
targetObject
Required. The object that receives the stack property. It can be an error, a plain object, or an object made from your own class. Set its name and message first, so the first line of the stack shows them.
constructorOpt
Optional. A function that is currently on the call stack. This function, and every call it made, is left out of the stack. Pass the helper or constructor that created the error.
Return Value
Return Value
Description
undefined
Nothing is returned. The method works by adding a stack property to targetObject.
TypeError (thrown)
You passed something that is not an object, such as a number or undefined.
JavaScript Examples
Example 1 — Add a Stack to a Plain Object
A plain object has no stack. Call captureStackTrace() and the property appears.
JavaScript
const report = { name: "ReportError", message: "Report could not be saved" };
console.log("Before: " + typeof report.stack);
Error.captureStackTrace(report);
console.log("After: " + typeof report.stack);
console.log(report.stack.split("\n")[0]);
console.log("Has an at-line: " + report.stack.includes("\n at "));
payNow stack has plainHelper: true
payNow stack has payNow: true
payLater stack has tidyHelper: false
payLater stack has payLater: true
How It Works
Default behavior.new Error() records the stack where it runs, so the first line of the call list is plainHelper, a function that tells the reader nothing.
Hide the helper.tidyHelper passes itself as constructorOpt. The stack is captured again and starts at payLater, the function that asked for the error.
Compare the results. The first stack contains plainHelper (true); the second does not contain tidyHelper (false). Both still show the function that threw.
Example 3 — Give Your Own Class a Stack
Neither class below extends Error. Only the second one asks for a stack.
JavaScript
class QuietIssue {
constructor(message) {
this.name = "QuietIssue";
this.message = message;
}
}
class TrackedIssue {
constructor(message) {
this.name = "TrackedIssue";
this.message = message;
Error.captureStackTrace(this, TrackedIssue);
}
}
const quiet = new QuietIssue("Disk is full");
const tracked = new TrackedIssue("Disk is full");
console.log("QuietIssue stack: " + typeof quiet.stack);
console.log("TrackedIssue stack: " + typeof tracked.stack);
console.log(tracked.stack.split("\n")[0]);
console.log("Is it an Error? " + (tracked instanceof Error));
QuietIssue stack: undefined
TrackedIssue stack: string
TrackedIssue: Disk is full
Is it an Error? false
How It Works
Two classes, one difference. Neither class extends Error. QuietIssue only sets name and message, so it has no stack.
Capture inside the constructor.TrackedIssue calls Error.captureStackTrace(this, TrackedIssue). Every new object gets a stack, and the constructor itself is hidden from it.
Still not an Error. The stack exists, but instanceof Error is false. When you can, extend Error instead; use this trick for classes that cannot.
Compatibility
Browser & Runtime Support
Error.captureStackTrace() started in the V8 engine and is not part of the JavaScript standard. Other engines have added it over time, but the stack text differs between engines.
✓ Non-standard · V8 API
Error.captureStackTrace()
Supported in Chrome, Edge, Opera, Node.js, Deno and Bun. Safari and Firefox support depends on the version, so check before you use it in browser code.
V8Engine it started in
Google ChromeSupported · Desktop & Mobile
Full support
Microsoft EdgeSupported · Chromium
Full support
OperaSupported · Chromium based
Full support
Samsung InternetSupported · Android
Full support
Android WebViewSupported · Chromium based
Full support
Node.jsSupported · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Mozilla FirefoxNewer versions · check the version
Check support
Apple SafariCheck the version · macOS & iOS
Check support
Internet ExplorerNo native support
Not supported
Error.captureStackTrace()Check first
Bottom line: Great in Node.js and Chromium browsers. In code that must run everywhere, test typeof Error.captureStackTrace === "function" first and skip the call when it is missing.
Frequently Asked Questions
It adds a stack property to the object you pass in. The stack is text: the first line is the name and message of the object, and the next lines list the functions that were running when you called the method. It returns nothing.
It hides one function from the top of the stack. Pass the helper or constructor that creates the error, and the stack will start at the code that called it. That makes the first line of the stack point at the real cause instead of at your error-building code.
Usually not. Calling super(message) already creates a stack, and V8 leaves the constructor out of it for you. Use captureStackTrace() for objects that do not extend Error, or to hide a helper function that builds errors.
Then there is nothing to cut at, and the stack contains only the first line (name and message) with no "at" lines. Always pass a function that is really running, such as the helper or constructor that made the error.
It started in V8, so Chrome, Edge and Node.js have it; other engines may not, so check typeof Error.captureStackTrace before you call it. In V8 the stack keeps 10 lines by default, controlled by Error.stackTraceLimit.