WebAssembly.Exception.prototype.stack
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Non-standard: This feature is not standardized. We do not recommend using non-standard features in production, as they have limited browser support, and may change or be removed. However, they can be a suitable alternative in specific cases where no standard option exists.
The stack read-only property of the WebAssembly.Exception object may contain a stack trace.
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, 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}
Description
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 the 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.
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.
(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 module 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 significant 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.