{"record":{"id":"1c559e004c75efe3","repo":"dotnet/runtime","slug":"unsupported-webcil-version-webcilversion","errorCode":null,"errorMessage":"Unsupported Webcil version: ${webcilVersion}","messagePattern":"Unsupported Webcil version: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/native/libs/Common/JavaScript/host/assets.ts","lineNumber":60,"sourceCode":"        loadedAssemblies.set(virtualPath, { ptr, length: bytes.length });\n        loadedAssemblies.set(shortName, { ptr, length: bytes.length });\n    } finally {\n        _ems_.stackRestore(sp);\n    }\n}\n\nexport async function instantiateWebcilModule(webcilPromise: Promise<Response>, memory: WebAssembly.Memory, virtualPath: string): Promise<void> {\n\n    const imports: WebAssembly.Imports = {\n        webcil: {\n            memory,\n        }\n    };\n\n    const { instance } = await instantiateWasm(webcilPromise, imports);\n    const webcilVersion = (instance.exports.webcilVersion as WebAssembly.Global).value;\n    if (webcilVersion !== 0) {\n        throw new Error(`Unsupported Webcil version: ${webcilVersion}`);\n    }\n\n    const sp = _ems_.stackSave();\n    try {\n        const sizePtr = _ems_.stackAlloc(sizeOfPtr);\n        const getWebcilSize = instance.exports.getWebcilSize as (destPtr: number) => void;\n        getWebcilSize(sizePtr as any);\n        const payloadSize = _ems_.HEAPU32[sizePtr as any >>> 2];\n\n        if (payloadSize === 0) {\n            throw new Error(\"Webcil payload size is 0\");\n        }\n\n        const ptrPtr = _ems_.stackAlloc(sizeOfPtr);\n        if (_ems_._posix_memalign(ptrPtr as any, 16, payloadSize)) {\n            throw new Error(\"posix_memalign failed for Webcil payload\");\n        }\n","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/dotnet/runtime/blob/290d5ab72cc1102813fbc0406fb186ceadabc340/src/native/libs/Common/JavaScript/host/assets.ts#L42-L78","documentation":"instantiateWebcilModule (host/assets.ts) instantiates the Webcil interpreter WASM module and reads its exported webcilVersion global. The loader expects exactly version 0; any other value means the Webcil .wasm shipped by this runtime is incompatible with the JS host code, and it throws naming the version found.","triggerScenarios":"A mismatch between the dotnet.runtime.js / dotnet.native.js host and the webcil.wasm interpreter module — e.g. the webcil wasm was replaced by a newer/older version that bumped its ABI version export.","commonSituations":"Manually swapping webcil.wasm from a different .NET release; partial upgrade where some framework files were updated but webcil.wasm was cached/left behind; CDN serving a stale webcil.wasm; build pipeline mixing artifacts from two SDK versions.","solutions":["Republish the project so all framework files (dotnet.js, dotnet.runtime.js, dotnet.native.wasm, webcil.wasm) come from the same .NET SDK version.","Clear browser/CDN cache so the matching webcil.wasm is fetched.","If using a CDN, pin the version path instead of a floating tag.","Verify the deployed webcil.wasm hash matches the one in blazor.boot.json."],"exampleFix":"<!-- before: CDN serves mismatched webcil version -->\n<script src=\"https://cdn.example.com/dotnet/8.0.0/dotnet.js\"></script>\n<!-- webcil.wasm cached from 9.0.0 preview -->\n\n<!-- after: pin all artifacts to the same version -->\n<script src=\"https://cdn.example.com/dotnet/8.0.7/dotnet.js\"></script>\n<!-- bust cache for webcil.wasm too -->","handlingStrategy":"validation","validationCode":"// After instantiating webcil wasm, before relying on it\nconst version = (instance.exports.webcilVersion as WebAssembly.Global).value;\nif (version !== 0) throw new Error(`webcil.wasm ABI version ${version} — redeploy matching runtime files`);","typeGuard":"function isExpectedWebcilVersion(exports: any): boolean {\n  return (exports?.webcilVersion as WebAssembly.Global | undefined)?.value === 0;\n}","tryCatchPattern":"try {\n  await instantiateWebcilModule(promise, memory, path);\n} catch (err) {\n  if (/Unsupported Webcil version/.test(err.message)) {\n    // bust cache and reload once so all artifacts match\n    if (!location.href.includes('bust=')) location.href += '?bust=' + Date.now();\n  } else throw err;\n}","preventionTips":["Pin framework files to a specific .NET runtime version on CDNs.","Cache-bust all framework assets together on redeploy.","Add a post-deploy verification that webcil.wasm hash matches blazor.boot.json."],"tags":["webcil","version","wasm","compatibility","deployment"],"analyzedSha":"290d5ab72cc1102813fbc0406fb186ceadabc340","analyzedAt":"2026-08-06T19:57:01.276Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}