{"record":{"id":"b3d3e2318e291fd0","repo":"dotnet/aspnetcore","slug":"unexpected-renderer-id-rendererid-encountered","errorCode":null,"errorMessage":"Unexpected renderer ID '${rendererId}' encountered while discovering new state.","messagePattern":"Unexpected renderer ID '(.+?)' encountered while discovering new state\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/Components/Web.JS/src/Services/WebRootComponentManager.ts","lineNumber":328,"sourceCode":"          // and if there are no updates on this batch, push an empty set of operations\n          // to ensure we send the state over. Same for wasm below.\n          serverState = discoverServerPersistedState(document) || '';\n          if (serverState && serverState !== '') {\n            const ops = operationsByRendererId.get(WebRendererId.Server);\n            if (!ops) {\n              operationsByRendererId.set(WebRendererId.Server, []);\n            }\n          }\n        } else if (rendererId === WebRendererId.WebAssembly) {\n          webAssemblyState = discoverWebAssemblyPersistedState(document) || '';\n          if (webAssemblyState && webAssemblyState !== '') {\n            const ops = operationsByRendererId.get(WebRendererId.WebAssembly);\n            if (!ops) {\n              operationsByRendererId.set(WebRendererId.WebAssembly, []);\n            }\n          }\n        } else {\n          throw new Error(`Unexpected renderer ID '${rendererId}' encountered while discovering new state.`);\n        }\n      }\n    }\n\n    for (const [rendererId, operations] of operationsByRendererId) {\n      const batch: RootComponentOperationBatch = {\n        batchId: this._nextOperationBatchId++,\n        operations,\n      };\n      this._pendingOperationBatches[batch.batchId] = batch;\n      const batchJson = JSON.stringify(batch);\n\n      if (rendererId === WebRendererId.Server) {\n        updateServerRootComponents(batchJson, serverState);\n      } else {\n        this.updateWebAssemblyRootComponents(batchJson, webAssemblyState);\n      }\n    }","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/3600ca084e9c8b5f4174fc5e747f4c52d2100806/src/Components/Web.JS/src/Services/WebRootComponentManager.ts#L310-L346","documentation":"While discovering persisted root-component state from the document, the manager iterates known renderer IDs (Server, WebAssembly). If it encounters a rendererId that is neither WebRendererId.Server (1) nor WebRendererId.WebAssembly (2), the discovery logic has no branch for it and throws. This guards against an unknown/out-of-range renderer ID appearing in persisted state.","triggerScenarios":"Thrown at line 328 inside the new-state discovery switch/if-chain when rendererId is not Server and not WebAssembly. The branch order implies only those two are expected for persisted interactive state.","commonSituations":"Version skew where a newer runtime emits a renderer ID the older JS bundle does not handle; custom interop injecting an unrecognized renderer ID; a stale blazor.boot.json or persisted state from a different framework version loaded by a newer/older client.","solutions":["Match the Blazor JS bundle version to the runtime that produced the persisted state.","Clear persisted state / cache and reload to regenerate it with matching versions.","Avoid injecting custom renderer IDs into Blazor's root-component persisted state.","Upgrade or downgrade all Blazor packages (server + client + JS) to the same release."],"exampleFix":"// before: client bundle v8 with persisted state from server v9 introducing a new renderer ID\n// after: align versions\n//   <script src=\"_framework/blazor.web.js\" autostart=\"false\"></script>\n// matched to the same Microsoft.AspNetCore.Components.Web assembly version","handlingStrategy":"validation","validationCode":"import { WebRendererId } from '../Rendering/WebRendererId';\nfunction isKnownPersistedRenderer(id: number): boolean {\n  return id === WebRendererId.Server || id === WebRendererId.WebAssembly;\n}\n// if (!isKnownPersistedRenderer(rendererId)) { /* version skew: reload with matching bundle */ }","typeGuard":"function isWebRendererId(v: unknown): v is number {\n  return typeof v === 'number' && v >= 0 && v <= 4;\n}","tryCatchPattern":"try {\n  // discovery\n} catch (e) {\n  if (/Unexpected renderer ID/i.test((e as Error).message)) {\n    // clear cache and reload with aligned versions\n    window.location.reload();\n  } else throw e;\n}","preventionTips":["Align Blazor JS bundle and runtime versions.","Do not inject custom renderer IDs into persisted state.","Clear persisted state / cache when upgrading Blazor versions.","Test upgrades with a clean browser profile."],"tags":["blazor","root-components","renderer-id","version-skew","persisted-state"],"backgroundTag":null,"analyzedSha":"3600ca084e9c8b5f4174fc5e747f4c52d2100806","analyzedAt":"2026-08-11T16:32:30.678Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}