Chrome DevTools maps DWARF-backed Wasm to original C/C++ sources, while source maps trade detail for reach. Use this 2026 cheat sheet. Read now.
What this cheat sheet covers
WebAssembly debugging in the browser usually comes down to one practical choice: keep rich language-level detail with DWARF, or accept thinner mapping in exchange for broader tooling reach with source maps. Chrome DevTools can map DWARF-backed Wasm back to the original C and C++ sources you shipped from, so breakpoints, stepping, and stack inspection land on real functions, locals, and types instead of raw module offsets. That is the path you want when you own the build and can emit debug info.
Source maps still matter. They are the portable bridge when DWARF is missing, stripped, or not supported end to end. You get line-level correlation and usable call stacks for many workflows, but you typically lose the deeper C and C++ view—typed locals, precise frame layout, and the same fidelity you expect from a native debugger. Treat this as a trade of detail for reach, not as a lesser version of the same thing.
DWARF-backed Wasm in Chrome DevTools
Start with a debug build that keeps DWARF in the module (or in a companion file your toolchain wires up). Load the page, open DevTools, and confirm the original sources appear under the Wasm module rather than only disassembly. Set breakpoints in the C or C++ file, trigger the path that runs that function, and step through as you would in a native session. Watch locals and the call stack; if names and types look wrong, the module is almost always built without full debug info or the browser never received it.
When something fails only in production-like builds, bisect the pipeline: optimize level, link flags that strip symbols, and whether the serving layer drops large debug sections. Prefer a dedicated debug artifact for local repro over turning every release build into a full debug module. Keep the same source tree revision you compiled against so line numbers still match.
When source maps are the right tool
Use source maps when your stack emits them by default, when you mix languages or toolchains that do not produce DWARF for the browser, or when you need a lightweight map that travels with minified or multi-step builds. They help you open the originating file, jump to a line from a stack frame, and reason about control flow without learning Wasm bytecode first.
Expect limits. Source maps describe locations more than full language runtime state. You may still need disassembly or a second debug build when the bug is in low-level memory use, calling convention, or a trap that only makes sense with native-style frames. Prefer source maps for day-to-day navigation and crash triage; switch to DWARF when you need depth.
- DWARF path: own the C/C++ build, need typed locals and accurate frames in Chrome DevTools.
- Source map path: need portable line mapping across more toolchains and lighter artifacts.
- Hybrid path: ship source maps broadly; keep a DWARF debug build for hard bugs.
A short debugging workflow
Reproduce under DevTools with caching disabled so you always load the build you think you loaded. Confirm which mapping you have—original C/C++ sources from DWARF, mapped sources from a source map, or only Wasm text and hex. Fix the mapping first if the UI only shows module offsets; no amount of stepping helps if you are not looking at the right file.
Then isolate: one breakpoint at the boundary between JS and Wasm, one inside the suspect function, and inspect values at each hop. For memory bugs, log or inspect linear memory near the faulting address after you know the source line. Document which build mode, mapping type, and entry URL you used so the next session starts from a known-good baseline. That is the 2026 cheat sheet in practice: pick the mapping that matches the bug, verify the sources load, then debug at the level of detail you actually have.