{"id":16543,"library":"stack-chain","title":"V8 Stack Trace Manipulation","description":"stack-chain is a utility library for Node.js that provides an API to intercept, modify, and reformat V8 JavaScript engine's stack traces. It allows developers to programmatically extend, filter, and replace the default stack trace formatting behavior of `Error.stack`. This is particularly useful for tools that need to clean up stack traces (e.g., hide internal frames in frameworks), provide custom error reporting, or integrate with debugging utilities. The current stable version is 2.0.0. The project appears to be abandoned, with the last publish over 8 years ago and last commit in 2017. This means it may not be compatible with newer Node.js versions or modern JavaScript features like ESM, and new releases or bug fixes are highly unlikely. Its key differentiator was offering a centralized, hook-based system for manipulating global `Error.stack` behavior.","status":"abandoned","version":"2.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/AndreasMadsen/stack-chain","tags":["javascript","stack","chain","trace","call site","concat","format"],"install":[{"cmd":"npm install stack-chain","lang":"bash","label":"npm"},{"cmd":"yarn add stack-chain","lang":"bash","label":"yarn"},{"cmd":"pnpm add stack-chain","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is primarily CommonJS. While a transpiler might allow `import`, direct ESM support is not provided, and `require` is the intended usage.","wrong":"import chain from 'stack-chain';","symbol":"chain","correct":"const chain = require('stack-chain');"},{"note":"The main export is a single 'chain' object with nested methods; individual functions are not directly exportable as named imports.","wrong":"import { extend } from 'stack-chain'; extend.attach(modifier);","symbol":"chain.extend.attach","correct":"const chain = require('stack-chain');\nchain.extend.attach(modifier);"},{"note":"This method replaces the global V8 stack formatter, allowing custom string output for `Error.stack`.","symbol":"chain.format.replace","correct":"const chain = require('stack-chain');\nchain.format.replace(formatter);"}],"quickstart":{"code":"const chain = require('stack-chain');\n\n// Attach a filter to remove frames originating from this file\nchain.filter.attach(function (error, frames) {\n    const filteredFrames = frames.filter(function (callSite) {\n        return callSite.getFileName() !== module.filename;\n    });\n    return filteredFrames;\n});\n\n// Replace the stack formatter to add a custom prefix\nchain.format.replace(function (error, frames) {\n    let lines = [];\n    lines.push(`CUSTOM ERROR: ${error.toString()}`);\n    for (let i = 0; i < frames.length; i++) {\n        lines.push(`    at (custom) ${frames[i].toString()}`);\n    }\n    return lines.join('\\n');\n});\n\nfunction myFunction() {\n    const err = new Error('Something went wrong!');\n    console.log(err.stack);\n}\n\nmyFunction();\n\n// Restore default V8 formatter after some time (note gotcha on restore)\nsetTimeout(() => {\n  chain.format.restore();\n  console.log('\\nRestored default stack format, but existing errors may not reflect it.');\n  const err2 = new Error('Another error after restore');\n  console.log(err2.stack);\n}, 100);","lang":"javascript","description":"Demonstrates how to attach a stack frame filter and replace the global stack trace formatter, then trigger and print an error."},"warnings":[{"fix":"Thoroughly test `stack-chain` in your environment, especially if other global error handlers or debugging tools are in use. Consider encapsulating its use or only enabling it in specific execution contexts.","message":"Modifying `Error.stack` globally can lead to conflicts with other libraries or tools that also attempt to manipulate stack traces, causing unpredictable behavior or race conditions. Use with caution in shared environments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be aware of the caching behavior of V8 `Error` objects. If you need to ensure a restored format, primarily apply `restore()` before new errors are generated or before their stacks are accessed.","message":"Calling `chain.format.restore()` does not guarantee that `Error.stack` will revert to its original V8 format for all existing `Error` objects. If `Error.stack` or `Error.callSite` has already been accessed on an `Error` object, its value is cached and will not change. Only newly created errors or errors whose stack hasn't been accessed will reflect the restored formatter.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new projects or existing projects on recent Node.js versions, consider alternative, actively maintained stack manipulation libraries or native V8 APIs directly. If using this package, thorough compatibility testing with your specific Node.js version is essential.","message":"The project is abandoned (last commit 2017, last publish 2014) and may not be compatible with modern Node.js versions (e.g., >Node 8-10) or recent V8 engine changes. APIs it relies on (V8 Stack Trace API) might have evolved or been removed, leading to unexpected behavior or crashes.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always ensure your modifier function for `attach` methods explicitly returns an array of `callSite` objects, even if it's the original, unmodified array.","message":"When using `chain.filter.attach` or `chain.extend.attach`, your modifier function *must* return a modified `frames` array. Failing to return an array, or returning `null` or `undefined`, can break subsequent modifiers or the stack trace generation process, leading to unexpected errors or incomplete stack traces.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Review your `modifier` functions. Ensure they always return an array, and that array contains valid `CallSite` objects. Do not mutate `CallSite` objects in ways that remove essential properties if they are expected by subsequent processors.","cause":"A stack modifier function (either `extend` or `filter`) returned something other than an array of V8 `CallSite` objects, or modified the objects in an unexpected way.","error":"TypeError: Cannot read properties of undefined (reading 'toString') (or similar for CallSite methods)"},{"fix":"Verify that `stack-chain` is the last or only library modifying `Error.stack` at the global level. Ensure `chain.format.replace` is called early in your application's lifecycle, before `Error.stack` is likely to be accessed for the first time on relevant error objects.","cause":"Another library or a custom setup is also modifying `Error.stack`, or `Error.stack` was already accessed on the error object before `chain.format.replace` was called.","error":"Error: `Error.stack` is not formatted as expected after calling `chain.format.replace`"},{"fix":"Convert your module to CommonJS by using `.js` extension with `\"type\": \"commonjs\"` in `package.json`, or rename your file to `.cjs`. Alternatively, if you must use ESM, you can try dynamic `import('stack-chain')` or a build step to transpile, but direct compatibility is not guaranteed for an abandoned package.","cause":"Attempting to use CommonJS `require` syntax directly within an ECMAScript Module (ESM) context in Node.js.","error":"ReferenceError: require is not defined (when using `require('stack-chain')` in an ESM module)"}],"ecosystem":"npm"}