WebAssembly.Exception.prototype.stack

Value

A string containing the stack trace, or undefined if no trace has been assigned.

The stack trace string lists the locations of each operation on the stack in WebAssembly format. This is a human-readable string indicating the URL, name of the function type called, the function index, and its offset in the module binary. It has approximately this format (see stack trace conventions in the specification for more information):

${url}:wasm-function[${funcIndex}]:${pcOffset}

Examples

This example demonstrate how to throw an exception from WebAssembly that includes a stack trace.

Consider the following WebAssembly code, which is assumed to be compiled to a file named example.wasm. This imports a tag, which it refers to as $tagname internally, and imports a function that it refers to as $throwExnWithStack. It exports the method run that can be called by external code to call $throwExnWithStack (and hence the JavaScript function).

(module
  ;; import tag that will be referred to here as $tagname
  (import "extmod" "exttag" (tag $tagname (param i32)))

  ;; import function that will be referred to here as $throwExnWithStack
  (import "extmod" "throwExnWithStack" (func $throwExnWithStack (param i32)))

  ;; call $throwExnWithStack passing 42 as parameter
  (func (export "run")
    i32.const 42
    call $throwExnWithStack
  )
)

The JavaScript code below defines a new tag tag and the function throwExceptionWithStack. These are passed to the WebAssembly module in the importObject when it is instantiated.

Once the file is instantiated, the code calls the exported WebAssembly run() method, which will immediately throw an exception. The stack is then logged from the catch statement.

const tag = new WebAssembly.Tag({ parameters: ["i32"] });

function throwExceptionWithStack(param) {
  // Note: We declare the exception with "{traceStack: true}"
  throw new WebAssembly.Exception(tag, [param], { traceStack: true });
}

// Note: importObject properties match the WebAssembly import statements.
const importObject = {
  extmod: {
    exttag: tag,
    throwExnWithStack: throwExceptionWithStack,
  },
};

WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject)
  .then((obj) => {
    console.log(obj.instance.exports.run());
  })
  .catch((e) => {
    console.log(`stack: ${e.stack}`);
  });

// Log output (something like):
// stack: throwExceptionWithStack@http://<url>/main.js:76:9
// @http://<url>/example.wasm:wasm-function[3]:0x73
// @http://<url>/main.js:82:38

The most "relevant" part of this code is the line where the exception is created:

new WebAssembly.Exception(tag, [param], { traceStack: true });

Passing in {traceStack: true} tells the WebAssembly virtual machine that it should attach a stack trace to the returned WebAssembly.Exception. Without this, the stack would be undefined.

Browser compatibility

See also

• WebAssembly overview
• WebAssembly concepts
• Using the WebAssembly JavaScript API