Rust team warns of WebAssembly change

WebAssembly targets for Rust will soon face a change that could risk breaking existing projects, according to an April 4 bulletin in the official Rust blog. The bulletin notes that all WebAssembly targets in Rust have been linked using the --allow-undefined flag to wasm-ld, but this flag is being removed.

Removing --allow-undefined on wasm targets is being done in rust-lang/rust#149868. That change is slated to land in nightly builds soon and will be released with Rust 1.96 on 2026-05-28. The bulletin explains that all WebAssembly binaries in Rust are created by linking with wasm-ld, thus serving a similar purpose to ld, lld, and mold. Since the first introduction of WebAssembly targets in Rust, the --allow-undefined flag has been passed to wasm-ld.

However, by passing --allow-undefined on all WebAssembly targets, rustc introduces diverging behavior between other platforms and WebAssembly, the bulletin says. The main risk of --allow-undefined is that misconfiguration or mistakes in building can result in broken WebAssembly modules being produced, as opposed to compilation errors. The bulletin lists the following example problematic situations:

• If mylibrary_init was mistakenly typed as mylibraryinit, then the final binary would import the mylibraryinit symbol instead of calling the linked mylibrary_init C symbol.
• If mylibrary was mistakenly not compiled and linked into a final application, then the mylibrary_init symbol would end up imported rather than producing a linker error saying it’s undefined.
• If external tools are used to process a WebAssembly module, such as wasm-bindgen or wasm-tools component new, they are likely to provide an error message that isn’t clearly connected back to the original source code from which the symbols were imported.
• Web errors along the lines of Uncaught TypeError: Failed to resolve module specifier "env". Relative references must start with either "/", "./", or "../".can mean that "env" leaked into the final module unexpectedly and the true error is the undefined symbol error, not the lack of "env" items provided.

All native platforms consider undefined symbols to be an error by default. Therefore, by passing --allow-undefined rustc introduces surprising behavior on WebAssembly targets. The goal of the change is to remove this surprise so that WebAssembly behaves more like native platforms, the bulletin states.

In theory, however, not a lot is expected to break from this change, the bulletin concludes. If the final WebAssembly binary imports unexpected symbols, then it’s likely the binary won’t be runnable in the desired embedding, as the desired embedding probably doesn’t provide the symbol as a definition. Therefore, most of the time this change will not break users, but will instead provide better diagnostics.