WebAssembly.Exception.prototype.stack
=====================================

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

The read-only **`stack`** property of an object instance of type `WebAssembly.Exception` *may* contain a stack trace.

Exceptions from WebAssembly code do not include a stack trace by default.

 If WebAssembly code needs to provide a stack trace, it must call a JavaScript function to create the exception, passing `options.traceStack=true` parameter in the constructor.
 The virtual machine can then attach a stack trace to the exception object returned by the constructor.


**Note:** Stack traces are not normally sent from WebAssembly code to improve performance.
 The ability to add stack traces to these exceptions is provided for developer tooling, and is not generally recommended for broader use.


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).


```wasm
(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.


```js
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:


```js
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
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebAssembly overview
* WebAssembly concepts
* Using the WebAssembly JavaScript API