WebAssembly Debugging Cheat Sheet [2026 Reference]

Debugging Stack at a Glance

Emscripten officially supports both DWARF and source maps for source-level debugging. The tradeoff is straightforward:

• DWARF offers the best debugging experience in Chrome, including better variable and call-stack inspection.
• Source maps are more widely supported, but they mainly provide source location mapping and are not a substitute for rich variable inspection.
• Memory Inspector complements both by exposing the raw WebAssembly.Memory buffer.
• Debug preservation is not automatic. In Emscripten, the final output still depends on link-time flags.

Pick the right artifact

• Choose DWARF for browser stepping, locals, scopes, and better inline-aware traces.
• Choose source maps when you want optimized output and source line mapping without shipping full DWARF in the main binary.
• Choose -g2 when you mainly want readable function names and low overhead.
• Choose separate DWARF when production payload size matters but developers still need source-level debugging.

Keyboard Shortcuts

These are the high-value shortcuts to keep your hands off the mouse while debugging Wasm in the Sources panel.

Commands by Purpose

Filter the snippets below by flag, tool, or use case.

emcc -g source.cc -o app.html

emcc source.c -c -o source.o -g
emcc source.o -o app.js -gsource-map --source-map-base https://debug.example.com/maps/

emcc source.c -c -o source.o -g
emcc source.o -o app.js -gsource-map=inline

emcc -g source.cc -o app.html \
  -gseparate-dwarf=app.debug.wasm \
  -sSEPARATE_DWARF_URL=https://debug.example.com/dwarf/app.debug.wasm

emcc source.c -c -o source.o
emcc source.o -o app.js -g2

emcc source.c -c -o source.o -gline-tables-only
emcc source.o -o program2.js -g
llvm-strip program2.wasm -o program2_stripped.wasm

emcc -O1 -sASSERTIONS test/hello_world.c
emcc -O1 -sSAFE_HEAP=1 test/hello_world.c

new Uint8Array(wasmMemory.buffer, ptr, len)
new DataView(wasmMemory.buffer).getUint32(ptr, true)
new DataView(wasmMemory.buffer).getFloat64(ptr, true)

Configuration

Default recipes

• Local stepping build: compile and link with -g, then debug in Chrome with the C/C++ DevTools Support (DWARF) extension.
• Optimized repro build: compile with -g, link with -gsource-map, and keep your normal optimization settings.
• Small production binary with debug fallback: use -gseparate-dwarf and host the sidecar through SEPARATEDWARFURL.
• Fast developer stacks: use -g2 when you only need names and readable stack traces.

Path and hosting fixes

• Use --source-map-base to point the generated Wasm at the correct source-map host.
• Use -sSOURCEMAPPREFIXES=/old/path=/new/path to rewrite source paths inside the map.
• If you build on a different machine or inside a container, Chrome's C/C++ DevTools Support (DWARF) extension can remap old and new file paths.

emcc source.c -c -o source.o -g
emcc source.o -o app.js \
  -gsource-map \
  --source-map-base https://debug.example.com/maps/ \
  -sSOURCE_MAP_PREFIXES=/build/src=/src

Memory Inspection

Memory Inspector is available from Chrome 91. For full Wasm object-memory workflows in C/C++, Chrome documents the best experience on Chrome 107+ with the C/C++ DevTools Support (DWARF) extension installed.

How to open it

• From DevTools: More tools > Memory inspector.
• While paused: click Reveal in Memory Inspector from the variable in Scope.
• You can inspect multiple objects at once in separate tabs.

What it is good at

• Jumping to exact addresses in hex.
• Switching between big-endian and little-endian views.
• Reading integer and floating-point interpretations without writing ad hoc parsing code.
• Following Pointer 32-bit and Pointer 64-bit jump targets when the addresses are valid.

// Common console helpers while paused
const bytes = new Uint8Array(wasmMemory.buffer, ptr, len)
const dv = new DataView(wasmMemory.buffer)
const u32 = dv.getUint32(ptr, true)
const f64 = dv.getFloat64(ptr, true)

Safe workflow for real incidents

• Pause at the suspect write or read.
• Inspect the source-level variable first through DWARF.
• If the value looks impossible, open Memory Inspector and validate the backing bytes.
• Before sharing copied buffers or dumps externally, scrub secrets with the Data Masking Tool.

Advanced Usage

When DWARF beats source maps

• DWARF carries richer type, variable, and inline information.
• Source maps survive aggressive post-link optimization better and are easier for broad ecosystem tooling.
• If stack accuracy matters more than portability, prefer DWARF.

Profiling caveat

• Chrome documents that when DevTools is open for Wasm debugging, the code it runs is not optimized; it is tiered down for a better debugging experience.
• Do not trust console.time() or performance.now() collected under an attached DevTools session as your primary performance signal.
• Use the Performance panel, or profile without DevTools open and inspect output afterward.

Minimal decision matrix

• Need variables, scopes, and line stepping: use -g.
• Need optimized line mapping without full symbolic payload: use -gsource-map.
• Need small artifacts plus later debugging: use -gseparate-dwarf.
• Need readable names only: use -g2.
• Need production crash line info with less debug bulk: use -gline-tables-only.

Official references checked

• Chrome DevTools: Debug C/C++ WebAssembly
• Chrome DevTools: Memory Inspector
• Chrome DevTools: Keyboard shortcuts
• Emscripten: Debugging
• Emscripten: emcc reference
• Emscripten: settings reference