JavaScript Error captureStackTrace() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Static method

Definition

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.

JavaScript
Error.captureStackTrace(targetObject);
Error.captureStackTrace(targetObject, constructorOpt);
CallWhat it does
Error.captureStackTrace(obj)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

ParameterDescription
targetObjectRequired. 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.
constructorOptOptional. 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 ValueDescription
undefinedNothing 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 "));
Try It Yourself

How It Works

  1. No stack yet. A plain object has no stack property, so typeof report.stack is "undefined".
  2. Capture. Error.captureStackTrace(report) adds report.stack and fills it with a string.
  3. Read the first line. The text starts with name: message taken from the object. The lines after it begin with at and name the code that was running.

Example 2 — Hide a Helper Function with constructorOpt

Two helpers build the same error. One of them passes itself as the second argument, so it does not show up in the stack.

JavaScript
function plainHelper(message) {
  return new Error(message);
}

function tidyHelper(message) {
  const problem = new Error(message);
  Error.captureStackTrace(problem, tidyHelper);
  return problem;
}

function payNow() {
  throw plainHelper("Card declined");
}

function payLater() {
  throw tidyHelper("Card declined");
}

try {
  payNow();
} catch (err) {
  console.log("payNow stack has plainHelper: " + err.stack.includes("plainHelper"));
  console.log("payNow stack has payNow: " + err.stack.includes("payNow"));
}

try {
  payLater();
} catch (err) {
  console.log("payLater stack has tidyHelper: " + err.stack.includes("tidyHelper"));
  console.log("payLater stack has payLater: " + err.stack.includes("payLater"));
}
Try It Yourself

How It Works

  1. 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.
  2. Hide the helper. tidyHelper passes itself as constructorOpt. The stack is captured again and starts at payLater, the function that asked for the error.
  3. 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));
Try It Yourself

How It Works

  1. Two classes, one difference. Neither class extends Error. QuietIssue only sets name and message, so it has no stack.
  2. Capture inside the constructor. TrackedIssue calls Error.captureStackTrace(this, TrackedIssue). Every new object gets a stack, and the constructor itself is hidden from it.
  3. 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.

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.

V8 Engine it started in
Google Chrome Supported · Desktop & Mobile
Full support
Microsoft Edge Supported · Chromium
Full support
Opera Supported · Chromium based
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Chromium based
Full support
Node.js Supported · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Mozilla Firefox Newer versions · check the version
Check support
Apple Safari Check the version · macOS & iOS
Check support
Internet Explorer No 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.

Next: Error.isError()

Learn how to check whether any value is a real Error object, even one thrown from another window.

Error.isError() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

12 people found this page helpful