↓ Skip to main content

Rust wasm-bindgen RuntimeError: unreachable executed in the Browser: Finding the Real Cause

Debugging Rust wasm-bindgen RuntimeError unreachable executed in the browser

I reloaded the page, clicked the button, and the console gave me this:

Uncaught RuntimeError: unreachable executed
    at wasm-function[142]:0x12a4f

The wording varies by browser, but it’s the same dead end everywhere. No file name, no Rust function, no reason. Just a function number and a hex offset, which is about as useful as a ZIP code for the middle of the ocean.

What that error actually is
#

On wasm32-unknown-unknown, a Rust panic doesn’t unwind and print a message. By default the panic aborts, and the abort lands on WebAssembly’s unreachable instruction. Anything that panics gets you here: an explicit panic!(), an .unwrap() on None, a slice index past the end. Without a panic hook you get something like RuntimeError: Unreachable executed, and with the hook installed you see the panic message. The message was never lost by accident. It was thrown away because nothing was listening.

Install the panic hook
#

console_error_panic_hook listens. It catches the panic, formats it, and sends it to console.error, where browser devtools typically capture a stack trace and display it with the logged message. Add it next to wasm-bindgen:

[dependencies]
wasm-bindgen = "0.2"
console_error_panic_hook = "0.1.7"

Register it once, early
#

Install the hook in the module’s start function so it’s in place before anything else runs:

use wasm_bindgen::prelude::*;

#[wasm_bindgen(start)]
pub fn main_js() -> Result<(), JsValue> {
    console_error_panic_hook::set_once();
    Ok(())
}

#[wasm_bindgen]
pub fn parse_payload(input: &str) -> String {
    let data: Vec<&str> = input.split(':').collect();
    data[5].to_string()
}

set_once exists for code paths that run more than once. It’s built on std::sync::Once, so the hook gets set a single time no matter how many times the initializer is called. That’s the whole benefit. It’s a guard, not a performance trick.

Build so the stack trace has names
#

There are two separate things you can see on a panic, and they depend on different settings.

The panic message and its file and line come from the panic itself, so you get them from the hook in any build, release included. What release builds drop is function names. Without debug symbols, the name section isn’t in the .wasm binary, and stack traces show names like wasm-function[42] instead of the Rust function. That’s the wasm-function[142] from the top.

For a debugging session, build with the debug profile:

wasm-pack build --target web --dev

A debug build gets symbols by default, and in a release build you can turn them on with debug = true under [profile.release] in Cargo.toml. If you need names in an optimized build, that’s the setting to use.

If you don’t use wasm-pack, the same thing works by hand. The wasm-pack GitHub organization was archived in 2025 along with the rest of the rustwasm org, but the tools carry on: wasm-bindgen moved to its own organization with development continuing, and wasm-pack was transferred to a new maintainer. Plenty of projects now skip it. wasm-pack is basically cargo build, then wasm-bindgen, then wasm-opt, so run those yourself, and run wasm-bindgen on the debug artifact:

cargo build --target wasm32-unknown-unknown
wasm-bindgen --target web --out-dir pkg \
  target/wasm32-unknown-unknown/debug/your_crate.wasm

One thing bites people on the manual path: the wasm-bindgen CLI version has to match the wasm-bindgen crate version in your Cargo.lock. When they differ, the CLI throws an error.

Read the real error
#

Reload, trigger the crash again, and the console now has the answer. On current toolchains it looks like this:

panicked at src/lib.rs:17:5:
index out of bounds: the len is 2 but the index is 5

That layout is newer than a lot of tutorials show. Since Rust 1.73, the default panic output puts the message on its own line and drops the surrounding quotes. Older posts show panicked at '...', src/lib.rs:17:5, with the message in quotes up front. If your output looks slightly different from either, your Rust version is why. The information is the same: what happened, and where.

Two console tips. First, read the first panic, not the last one. After a panic the module is in an unknown state, so later calls can fail with confusing follow-up errors that point you at the wrong thing. Second, raise the stack depth if the trace looks cut off. Many browsers only capture the top 10 stack frames, and Rust programs often need more. Setting Error.stackTraceLimit = 50 in the console before you reproduce the crash gets you a longer trace.

Usual suspects
#

Once the messages are readable, most of these crashes turn out to be the same few things.

The most common is unchecked access to data that came from JavaScript: .unwrap(), .expect(), or indexing a vector directly. The fix is to let the function fail properly. Return a Result<T, JsValue> and wasm-bindgen turns the Err into an exception your JS try/catch can handle:

#[wasm_bindgen]
pub fn parse_field(input: &str, index: usize) -> Result<String, JsValue> {
    input
        .split(':')
        .nth(index)
        .map(str::to_string)
        .ok_or_else(|| JsValue::from_str(&format!("field {index} missing")))
}

Next is Rc<RefCell<T>> shared between async closures and DOM event listeners. Calling borrow_mut() while a borrow() is still alive in the same call stack panics at runtime, and event-driven code makes it easy to do by accident.

Then there’s deserialization. If you pass a JS object into serde-wasm-bindgen and a required field is undefined or the wrong type, you get an error value, and an immediate .unwrap() on it turns that into a panic. Handle the Result and the failure becomes a readable error on the JS side.

The ones that surprise people are the standard library calls that don’t work in a browser at all. std::time::Instant::now() and SystemTime::now() simply panic on wasm32-unknown-unknown. The web-time crate is a drop-in replacement that uses Performance.now() for Instant and Date.now() for SystemTime, and it re-exports std::time on other targets. The other classic is randomness. If a dependency uses getrandom and you haven’t enabled its browser backend, it fails at runtime. The feature is called js on getrandom 0.2, and newer versions changed the setup, so check the docs for the version you’re on.

Keeping it out of production, or not
#

Gating the hook behind a feature flag is a common pattern. Crates wrap the call in #[cfg(feature = "console_error_panic_hook")] inside a small helper function. Making the hook default-on and optional keeps it easy to remove:

#[wasm_bindgen(start)]
pub fn init() {
    #[cfg(feature = "console_error_panic_hook")]
    console_error_panic_hook::set_once();
}

Think before you use #[cfg(debug_assertions)] instead. Release builds leave debug_assertions off, so that version ships production with no hook, and every panic your users hit is back to a bare unreachable. The hook costs some binary size, and I haven’t measured how much on your build, so compare your .wasm size with and without it before deciding. If a panic in production would otherwise be invisible, the message is worth the bytes.

unreachable executed isn’t the bug. It’s the receipt. The bug is whatever line printed it, and until you install the hook, nothing tells you which line that was.

Melvin
Author
Melvin
I am a software developer building high-performance local AI tools and web architectures. I created Sablegrid, a platform that automates project scoping end to end. Stellar Tech Labs is where I write up what I learn along the way.

Related

Comments