{"id":"08b470944810b3a6","repo":"vitejs/vite","slug":"no-matching-html-proxy-module-found-from-id","errorCode":null,"errorMessage":"No matching HTML proxy module found from ${id}","messagePattern":"No matching HTML proxy module found from (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vite/src/node/plugins/html.ts","lineNumber":131,"sourceCode":"      handler(id) {\n        return id\n      },\n    },\n\n    load: {\n      filter: { id: isHtmlProxyRE },\n      handler(id) {\n        const proxyMatch = htmlProxyRE.exec(id)\n        if (proxyMatch) {\n          const index = Number(proxyMatch[1])\n          const file = cleanUrl(id)\n          const url = file.replace(normalizePath(config.root), '')\n          const result = htmlProxyMap.get(config)!.get(url)?.[index]\n          if (result) {\n            // set moduleSideEffects to keep the module even if `treeshake.moduleSideEffects=false` is set\n            return { ...result, moduleSideEffects: true }\n          } else {\n            throw new Error(`No matching HTML proxy module found from ${id}`)\n          }\n        }\n      },\n    },\n  }\n}\n\nexport function addToHTMLProxyCache(\n  config: ResolvedConfig,\n  filePath: string,\n  index: number,\n  result: { code: string; map?: SourceMapInput },\n): void {\n  if (!htmlProxyMap.get(config)) {\n    htmlProxyMap.set(config, new Map())\n  }\n  if (!htmlProxyMap.get(config)!.get(filePath)) {\n    htmlProxyMap.get(config)!.set(filePath, [])","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/vitejs/vite/blob/89620f09afcfef6b35e7bb8660132ab5b4d0cd3b/packages/vite/src/node/plugins/html.ts#L113-L149","documentation":"Thrown by the HTML plugin's `load` hook for an HTML proxy module id when no cached result exists at the expected index. Vite stores inline scripts/styles extracted from HTML in `htmlProxyMap` keyed by URL and index; a `load` of an `?html-proxy&index=N` id with no matching entry means the proxy was requested before/without being registered.","triggerScenarios":"A request id matching `isHtmlProxyRE` reaches `load`; `htmlProxyRE.exec(id)` parses the index, but `htmlProxyMap.get(config).get(url)?.[index]` is undefined — so `result` is falsy and the error is thrown.","commonSituations":"Stale module graph after editing HTML files (HMR out of sync), a custom plugin requesting proxy ids, Vite version mismatch where the index format changed, or concurrent/SSR builds reusing a proxy map inconsistently.","solutions":["Restart the Vite dev server and clear `node_modules/.vite`.","Remove custom plugins that generate or import `?html-proxy` ids.","Ensure HTML entry files are not deleted/renamed mid-build.","Upgrade Vite — proxy indexing bugs are fixed in patch releases."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await load(id);\n} catch (e) {\n  if (/No matching HTML proxy module found/.test(e.message)) {\n    console.warn('Stale HTML proxy — restart Vite and clear .vite cache');\n  }\n  throw e;\n}","preventionTips":["Do not generate or import `?html-proxy` ids in custom plugins.","Restart the dev server and clear cache after Vite upgrades.","Avoid editing/deleting HTML entries mid-build."],"tags":["html","html-proxy","internal","hmr"],"analyzedSha":"89620f09afcfef6b35e7bb8660132ab5b4d0cd3b","analyzedAt":"2026-08-03T19:28:02.920Z","schemaVersion":2}