Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 Β· Performance and Debugging

Debugging WebAssembly

Learn to debug WebAssembly - reading traps, the name section and stack traces, DWARF debug info and source maps in browser DevTools, logging from wasm, and a checklist for common bugs.

Debugging a program you did not write in the language you are looking at is awkward. A WebAssembly module is a binary, the code you actually wrote was C or Rust, and the failing call arrives from JavaScript. The good news is that the pieces to bridge those gaps exist: engines report traps with stack traces, binaries can carry names for functions and variables, and browser DevTools can map machine instructions back to your original source lines.

This lesson walks through the tools from simplest to most powerful, and ends with a checklist for the bugs that show up again and again.

Traps: how Wasm fails

When something illegal happens inside a module, execution stops with a trap. In JavaScript it surfaces as a WebAssembly.RuntimeError (or, for stack exhaustion, a RangeError). The message tells you the category of the fault but not where it came from.

Cause Typical message in V8
Out-of-bounds memory access memory access out of bounds
Integer division by zero divide by zero
INT_MIN / -1 and similar divide result unrepresentable
unreachable instruction (also Rust panics, C abort) unreachable
Failed call_indirect type check null function or function signature mismatch
Table index out of range table index is out of bounds
Infinite recursion RangeError: Maximum call stack size exceeded

The exact text differs between engines, so test for the error class, not the message, in production code. Here is a module that triggers four different traps on demand:

Node.js Provoking and catching traps

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A trap does not corrupt anything: the call stops, the exception propagates to JavaScript, and you can keep using the instance (although its memory may now be in a half-updated state, so most programs discard the instance after an unexpected trap).

The name section: readable stack traces

A raw trap stack looks like wasm-function[1]:0x39, where the number is the function index and the hex value is a byte offset in the binary. That is exact but useless for humans. Compilers can add an optional custom section called name that maps indexes to function and local names. Engines use it to print at inner and at outer instead of numbers.

Names are optional because they cost bytes and do not affect behavior. Release builds usually strip them; development builds keep them. Here are two builds of the same module, with and without names. We force a trap and look at the stack lines, and use WebAssembly.Module.customSections to inspect the section directly:

Node.js Stack traces with and without the name section

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The "with names" build is only about 40 bytes bigger. For real modules the name section can be a large share of the file, which is why you strip it for production and keep a copy with names for symbolicating crash reports.

Source-level debugging in the browser

For a real project you want breakpoints in your C or Rust source, not in disassembled instructions. Two mechanisms exist.

DWARF debug info. Compile with -g (Emscripten) or a debug profile (Rust), and the module carries standard DWARF data, the same format native debuggers use. Chrome's DevTools can read it with the "C/C++ DevTools Support (DWARF)" extension, which lets you set breakpoints in .c or .rs files, step line by line, inspect local variables and even evaluate C expressions.

Terminal
# Emscripten: keep DWARF
emcc app.c -g -O0 -o app.js

# Rust: a debug build keeps debug info by default
cargo build --target wasm32-unknown-unknown

Source maps. The older approach (still supported by Emscripten via -gsource-map) writes a .wasm.map file that maps code offsets to lines, so you get line-level stepping but no variable inspection.

Debugging toolbox

Read the trap Class and message name the fault.
Name section Function names in stack traces.
Source maps Step through original lines.
DWARF Variables and expressions in DevTools.

Use -O0 and -g while debugging.

1 / 2

Optimizing builds make stepping confusing, because the compiler inlines functions, reorders statements and removes variables. Debug at -O0 (or opt-level = 0), then re-test the optimized build.

In Chrome DevTools open the Sources panel, find your .wasm module under the page's files, and click a line number to set a breakpoint. Firefox's debugger shows a text-format view of the module, and both browsers let you inspect the linear memory of an instance as a hex view in the scopes panel. Node.js supports node --inspect with the same Chrome DevTools UI.

Logging from inside the module

When a debugger is overkill, the simplest tool is an import. Give the module a function that prints a number or a string, and call it from your code (for C, printf with Emscripten does this for you, for Rust use console.log through web-sys or console_log). With a pointer and length you can print a string:

Node.js Log and hex-dump memory from the host

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Seeing the real bytes settles most arguments immediately: is the string where you think it is, is it the length you expect, did the module write past the end?

A checklist for common bugs

  1. LinkError on instantiate. An import is missing or has the wrong type. Print WebAssembly.Module.imports(module) and compare with your import object.
  2. CompileError. The file is truncated, served as text, or uses a feature the browser lacks. Check the Content-Type and validate with WebAssembly.validate.
  3. memory access out of bounds. Usually a pointer that is zero, uninitialized, or computed from a wrong length, or a buffer overrun in C. Run with sanitizers (-fsanitize=address in Emscripten) to find it.
  4. Garbled or truncated text. Mixed up characters and bytes, or a missing terminator.
  5. Zero-length views. Memory grew and you used a stale ArrayBuffer; recreate views after calls.
  6. unreachable with no explanation. A Rust panic or C abort. Install console_error_panic_hook in Rust, or look at the console output before the trap.
  7. Works in dev, fails in production. Optimization changed behavior (undefined behavior in C), or a stripped build lacks the file layout assumptions you coded against.

Check your understanding

Quick check Β· 4 questions

of 4 answered You scored / 4 Β· perfect!

  1. 1. What JavaScript error class does a trap such as divide by zero produce?

    Traps raised while executing a module are WebAssembly.RuntimeError. LinkError is for failed imports during instantiation.
  2. 2. What does the name custom section do?

    Names are purely informational. They improve diagnostics and can be stripped without changing behavior.
  3. 3. Which setup lets you step through your original C or Rust lines and inspect variables in Chrome DevTools?

    DWARF debug information carries source lines and variable locations; the extension lets DevTools use it.
  4. 4. Why is it better to debug an unoptimized (-O0) build?

    Inlining, reordering and variable elimination make the optimized code diverge from your source, so stepping looks erratic.

Summary

  • Illegal operations trap as WebAssembly.RuntimeError; check the class rather than the message text.
  • The name section gives readable stack traces and is stripped from release builds.
  • DWARF info or source maps let DevTools step through your original source; debug at -O0.
  • Import a log function and write a hexdump helper to inspect the boundary.
  • Most bugs are boundary mistakes: lengths, stale views, missing imports, pointers.

Next: Binary Size and Optimization