Emscripten "wasm-ld: error: undefined symbol" link failure in CI

By Daniel Zoghalchali·Latchkey

Emscripten's linker (wasm-ld) resolved every object file and still found a symbol with no definition. This is the classic missing-implementation link error: a declared function that nothing actually provides for the wasm target.

What this error means

An emcc link step fails with "wasm-ld: error: undefined symbol: X" and "emcc: error: ... wasm-ld ... failed". Compilation of each translation unit succeeded; only linking failed.

wasm-ld: error: undefined symbol: my_helper
>>> referenced by main.c
>>>               main.o
emcc: error: 'wasm-ld ...' failed (returned 1)

Common causes

A referenced function is not compiled or linked in

A source that defines the symbol was left out of the link command, or only its header was compiled, so wasm-ld has a declaration but no definition.

A JS library symbol not exposed to the linker

A function meant to come from a JS library was not provided with --js-library or the right EXPORTED_FUNCTIONS, so it stays undefined.

How to fix it

Link the object that defines the symbol

1. Add the missing source/object to the emcc link command.
2. For an intentionally late-bound symbol, allow it explicitly.
3. Re-run the link.

emcc main.c helper.c -o app.js

Allow undefined symbols supplied at runtime

If the symbol is provided by JavaScript at instantiation, tell wasm-ld to leave it undefined rather than fail.

emcc main.c -s ERROR_ON_UNDEFINED_SYMBOLS=0 -o app.js

How to prevent it

• Include every source that defines a referenced symbol in the link.
• Declare JS-provided symbols with the right library and exports.
• Keep ERROR_ON_UNDEFINED_SYMBOLS on to catch gaps early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation