1# Debugging WebAssembly with Core Dumps
2
3Wasmtime can be configured to generate [the standard Wasm core dump
4format][spec] whenever guest Wasm programs trap. These core dumps can then be
5consumed by external tooling (such as [`wasmgdb`][wasmgdb]) for post-mortem analysis.
6
7This page focuses on generating and inspecting core dumps via the Wasmtime
8command-line interface. For details on how to generate core dumps via the
9`wasmtime` embedding API, see [Core Dumps in a Rust
10Embedding](./examples-core-dumps.md).
11
12First, we need to compile some code to Wasm that can trap. Consider the
13following Rust code:
14
15```rust,no_run
16// trap.rs
17
18fn main() {
19    foo(42);
20}
21
22fn foo(x: u32) {
23    bar(x);
24}
25
26fn bar(x: u32) {
27    baz(x);
28}
29
30fn baz(x: u32) {
31    assert!(x != 42);
32}
33```
34
35We can compile it to Wasm with the following command:
36
37```console
38rustc --target wasm32-wasip1 -o ./trap.wasm ./trap.rs
39```
40
41Next, we can run it in Wasmtime and capture a core dump when it traps:
42
43```shell-session
44$ wasmtime -D coredump=./trap.coredump ./trap.wasm
45thread 'main' panicked at /home/nick/scratch/trap.rs:14:5:
46assertion failed: x != 42
47note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
48Error: failed to run main module `/home/nick/scratch/trap.wasm`
49
50Caused by:
51    0: core dumped at /home/nick/scratch/trap.coredump
52    1: failed to invoke command default
53    2: wasm coredump generated while executing store_name:
54       modules:
55         <module>
56       instances:
57         Instance(store=1, index=1)
58       memories:
59         Memory(store=1, index=1)
60       globals:
61         Global(store=1, index=0)
62       backtrace:
63       error while executing at wasm backtrace:
64           0: 0x5961 - <unknown>!__rust_start_panic
65           1: 0x562a - <unknown>!rust_panic
66           2: 0x555d - <unknown>!std::panicking::rust_panic_with_hook::h58e7d0b3d70e95b6
67           3: 0x485d - <unknown>!std::panicking::begin_panic_handler::{{closure}}::h1853004619879cfd
68           4: 0x47bd - <unknown>!std::sys_common::backtrace::__rust_end_short_backtrace::hed32bc5557405634
69           5: 0x4f02 - <unknown>!rust_begin_unwind
70           6: 0xac01 - <unknown>!core::panicking::panic_fmt::h53ca5bf48b428895
71           7: 0xb1c5 - <unknown>!core::panicking::panic::h62c2c2bb054da7e1
72           8:  0x661 - <unknown>!trap::baz::h859f39b65389c077
73           9:  0x616 - <unknown>!trap::bar::h7ad12f9c5b730d17
74          10:  0x60a - <unknown>!trap::foo::ha69c95723611c1a0
75          11:  0x5fe - <unknown>!trap::main::hdfcd9f2d150fc3dc
76          12:  0x434 - <unknown>!core::ops::function::FnOnce::call_once::h24336e950fb97d1e
77          13:  0x40b - <unknown>!std::sys_common::backtrace::__rust_begin_short_backtrace::h2b37384d2b1a57ff
78          14:  0x4ec - <unknown>!std::rt::lang_start::{{closure}}::he86eb1b6ac6d7501
79          15: 0x24f7 - <unknown>!std::rt::lang_start_internal::h21f6a1d8f3633b54
80          16:  0x497 - <unknown>!std::rt::lang_start::h7d256f21902ff32b
81          17:  0x687 - <unknown>!__main_void
82          18:  0x3e6 - <unknown>!_start
83       note: using the `WASMTIME_BACKTRACE_DETAILS=1` environment variable may show more debugging information
84```
85
86You now have a core dump at `./trap.coredump` that can be consumed by external
87tooling to do post-mortem analysis of the failure.
88
89[spec]: https://github.com/WebAssembly/tool-conventions/blob/main/Coredump.md
90[wasmgdb]: https://github.com/xtuc/wasm-coredump/blob/main/bin/wasmgdb/README.md
91