WebAssembly Module Instantiation Error Messages Differ Across Browsers for Identical Import Validation Failures

Standardized error message format and validation details

Browsers should attach a machine‑readable diagnostic to WebAssembly.LinkError that includes:

{
  "reason": "type_mismatch" | "missing_export" | "not_an_export" | "wrong_export_kind",
  "phase": "linking",
  "import": {
    "module": "env",
    "name": "add",
    "kind": "function",
    "mutability": "mutable" | "immutable" | "unknown",
    "type": "i32,i32->i32" | "anyfunc" | "unknown"
  },
  "expected": "i32,i32->i32",
  "actual": "i32,i32->f64"
}

Human‑readable error.message remains free‑form and non‑contractual.

Confirmed facts

• The WebAssembly JavaScript API defines CompileError for binary validation and LinkError for import linking; it does not prescribe exact message text.
• Engine‑specific formatting of host‑object descriptions and signature details varies, and some engines omit the expected/actual pair.
• Import validation occurs before execution; the error signals a linking failure, not a runtime exception.

Likely explanation of variance

Engines differ in how they describe host callables, which may lead to missing or ambiguous expected/actual type information. This formatting difference does not alter module semantics.

Tooling adaptation steps

1. Capture LinkError at the instantiation boundary and wrap the promise that returns it.
2. Classify the error using controlled fixtures that represent missing exports, wrong import kinds, and signature mismatches for each target browser version.
3. Attach engine name and version metadata to every captured error; keep the raw message and stack only for debugging.
4. Map observed messages to the stable reason codes defined above; never compare raw strings.
5. If the exact host import object (prototype chain and property descriptors) is not available, request that information to reconstruct expected versus actual types.

Missing diagnostic detail

Do you capture the exact host import object (including its prototype chain) that is passed to WebAssembly.instantiate? Providing this data is required to reliably reconstruct expected versus actual types when the engine reports unknown types.