Skip to content

docs: add exception handling toolchain compatibility guide #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shubham5080 wants to merge 4 commits into
base: main
Choose a base branch
from
+60 −0
Open

docs: add exception handling toolchain compatibility guide #310

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d2a7b4c
docs: add exception handling toolchain compatibility guide
shubham5080 Jul 7, 2026
7135b5a
docs: list toolchain versions in EH compatibility table
shubham5080 Jul 8, 2026
a2e805e
docs: move EH example into WasmEdge Book page
shubham5080 Jul 8, 2026
f070383
docs: drop unverified wasi-sdk row from EH table
shubham5080 Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions docs/develop/c/exception_handling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
sidebar_position: 6
---

# Exception Handling

WasmEdge implements the [latest exception-handling proposal](https://github.com/WebAssembly/exception-handling) (post Oct 2023). Legacy EH instructions such as `delegate` are rejected at load time.

Enable the proposal when running or compiling:

```bash
wasmedge --enable-exception-handling module.wasm
wasmedge compile --enable-exception-handling module.wasm module.aot.wasm
```

## Toolchain compatibility

| Toolchain | Compatible with WasmEdge EH | Notes |
|-----------|----------------------------|-------|
| Emscripten (`-fwasm-exceptions`) | No (as of 2026) | Often emits legacy EH (e.g. opcode `0x117` / `delegate`) |
| C/C++ via wasi-sdk / clang | Check your LLVM version | Must emit the latest EH proposal, not legacy EH |
Comment thread
shubham5080 marked this conversation as resolved.
Outdated
| `wasm-3.0-exceptions` spec tests | Yes | Official test inputs used by WasmEdge |

WasmEdge does not plan to support legacy EH. Use modules built for the current proposal only.

## How WasmEdge tests EH

CI runs the `wasm-3.0-exceptions` suite from [wasmedge-spectest](https://github.com/WasmEdge/wasmedge-spectest). See `test/spec/CMakeLists.txt` in the [WasmEdge](https://github.com/WasmEdge/WasmEdge) repository.

To run a spec test locally after building tests, or fetch a `.wasm` from that repository:

```bash
wasmedge --enable-exception-handling path/to/test.wasm
```

## Emscripten repro (expected failure today)

```bash
emcc -O1 -fwasm-exceptions -sSTANDALONE_WASM a.cpp -o a.wasm
wasmedge --enable-exception-handling a.wasm
```

Example `a.cpp` and more detail: [examples/exception_handling](https://github.com/WasmEdge/WasmEdge/tree/master/examples/exception_handling) in the WasmEdge repository.