{"record":{"id":"de2331760eb05b4e","repo":"dotnet/runtime","slug":"unsupported-webcil-version-webcilversion","errorCode":null,"errorMessage":"Unsupported Webcil version: ${webcilVersion}","messagePattern":"Unsupported Webcil version: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/coreclr/hosts/corerun/wasm/libCorerun.js","lineNumber":267,"sourceCode":"                        rtlRestoreContextTag: wasmExports.__coreclr_wasm_rtlrestorecontext_tag,\n                        table: wasmTable,\n                        tableBase: new WebAssembly.Global({ value: \"i32\", mutable: false }, tableStartIndex),\n                        imageBase: new WebAssembly.Global({ value: \"i32\", mutable: false }, payloadPtr),\n                        // Runtime-async continuation return value, shared with the runtime module.\n                        asyncContinuation: wasmExports.__async_continuation\n                    }\n                });\n            } catch (e) {\n                const errorMessage = e instanceof Error ? e.message : String(e);\n                console.error(\"Failed to construct WebAssembly instance for Webcil image:\", { wasmPath, errorMessage });\n                return false;\n            } finally {\n                stackRestore(sp);\n            }\n\n            const webcilVersion = wasmInstance.exports.webcilVersion.value;\n            if ((webcilVersion > 1) || (webcilVersion < 0)) {\n                throw new Error(`Unsupported Webcil version: ${webcilVersion}`);\n            }\n\n            wasmInstance.exports.getWebcilPayload(payloadPtr, payloadSize);\n            if (tableSize > 0) {\n                wasmInstance.exports.fillWebcilTable();\n            }\n            HEAPU32[outDataStartPtr >>> 2 >>> 0] = payloadPtr;\n            HEAPU32[outSize >>> 2 >>> 0] = payloadSize;\n            HEAPU32[(outSize + 4) >>> 2 >>> 0] = 0;\n            return true;\n        }\n    };\n    const patchNODERAWFS = {\n        cwd: () => {\n            // drop windows drive letter for NODEFS cwd to pretend we are in unix\n            const path = process.cwd();\n            return NODEFS.isWindows\n                ? path.replace(/^[a-zA-Z]:/, \"\").replace(/\\\\/g, \"/\")","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/dotnet/runtime/blob/60108ba66eb7d1d12f595480091b4ad80a24b172/src/coreclr/hosts/corerun/wasm/libCorerun.js#L249-L285","documentation":"Thrown by the Webcil host inside the corerun WebAssembly glue (libCorerun.js) after it instantiates the Webcil wasm image. The host only accepts the webcil protocol versions 0 and 1; any other value reported by the wasm export `webcilVersion` is treated as an incompatible runtime/host pairing and aborts loading the image. The check exists so a newer (or older) runtime binary cannot be silently driven by an incompatible host, which would corrupt the runtime payload.","triggerScenarios":"Reached only after a Webcil WebAssembly instance is successfully constructed for a Webcil image. The branch `webcilVersion > 1 || webcilVersion < 0` at src/coreclr/hosts/corerun/wasm/libCorerun.js:266-267 fires when `wasmInstance.exports.webcilVersion.value` is outside [0,1]. This happens when the Webcil payload (.dll/.webcil) is produced by a future or dev toolchain whose protocol version diverged from the corerun wasm host that emcc linked into the binary.","commonSituations":"Mixing a .NET runtime build from one branch with a corerun wasm host from another; upgrading the .NET SDK / runtime to a preview that bumped the webcil protocol without rebuilding the native corerun host; using a stale `dotnet.native.wasm` artifact alongside freshly built Webcil assemblies; man-in-the-middle/partial deploy that ships half of a runtime update.","solutions":["Rebuild both the Webcil assemblies and the corerun wasm host from the same source tree / SDK so the protocol version agrees.","Clean previous build outputs (bin/obj) and any cached wasm artifacts, then `dotnet publish` the project again.","Confirm the runtime package version reported by the loaded `dotnet.native.wasm` matches the SDK used to compile the Webcil images.","If you intentionally changed the webcil protocol, update the upper bound in libCorerun.js:266 to support the new version."],"exampleFix":"// before: mismatched artifacts after partial upgrade\n//  -> runtime throws `Unsupported Webcil version: 2`\n\n// after: rebuild from one source tree so host + payload agree\ndotnet clean && dotnet build -c Release\n// republish the wasm app to regenerate dotnet.native.wasm + webcil payloads\ndotnet publish -c Release -o ./publish","handlingStrategy":"validation","validationCode":"// Verify the webcil protocol version before instantiating\nfunction isSupportedWebcilVersion (wasmInstance) {\n  const v = wasmInstance?.exports?.webcilVersion?.value;\n  return typeof v === 'number' && v >= 0 && v <= 1;\n}\n// if (!isSupportedWebcilVersion(wasmInstance)) { /* abort with a clear message, rebuild */ }","typeGuard":"function isWebcilInstanceCompatible (inst: WebAssembly.Instance): boolean {\n  const v = (inst.exports as any).webcilVersion;\n  return v != null && typeof v.value === 'number' && v.value >= 0 && v.value <= 1;\n}","tryCatchPattern":null,"preventionTips":["Publish the runtime and Webcil assemblies from the same SDK/source tree in one step.","Treat the runtime bundle (dotnet.native.wasm + dotnet.runtime.js) and the Webcil payloads as an atomic unit in CI artefacts.","Pin the .NET SDK version in global.json and CI to prevent drift."],"tags":["webcil","wasm","runtime-host","version-mismatch","corerun"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}