{"record":{"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":132,"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":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/vitejs/vite/blob/b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab/packages/vite/src/node/plugins/html.ts#L114-L150","documentation":"The vite:html-inline-proxy plugin loads ids matching the HTML proxy pattern (e.g. file.html?html-proxy&index=N). It looks up the cached proxy result by url+index in htmlProxyMap; if no entry exists for that index it throws. Proxy entries are created by addToHTMLProxyCache during HTML transformation, so a missing entry means the proxy id was generated/referenced before (or without) the corresponding inline script/style being registered.","triggerScenarios":"An HTML file references an inline script/style chunk whose proxy index does not exist in the map — typically because the HTML was edited, cached, or transformed by a plugin that emits a stale proxy id. Also triggered when a plugin manually resolves/loads an html-proxy id without the matching addToHTMLProxyCache call.","commonSituations":"HMR leaving stale proxy references after the HTML inline blocks were re-indexed, a plugin injecting script tags that produce proxy ids Vite did not register, or build cache/transform customizations desyncing the index numbering.","solutions":["Restart the dev server / clear the Vite cache to drop stale proxy ids.","If a custom plugin transforms HTML and emits ?html-proxy&index=N ids, ensure it calls addToHTMLProxyCache for every index it produces.","Check for duplicate or conflicting HTML-transforming plugins that both rewrite inline scripts.","Update Vite and HTML-related plugins to pick up fixes around proxy index consistency."],"exampleFix":"// before — plugin emits proxy id but never registers it\nconst id = `${file}?html-proxy&index=${i}`\n// after\nimport { addToHTMLProxyCache } from 'vite'\naddToHTMLProxyCache(config, url, i, { code, map })","handlingStrategy":"validation","validationCode":"// If you emit proxy ids, validate the index exists before referencing\nfunction safeHtmlProxyLoad(map, url, index) {\n  const entry = map.get(url)?.[index]\n  if (!entry) throw new Error(`Missing proxy entry for ${url}[${index}]`)\n  return entry\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await load(id)\n} catch (e) {\n  if (/No matching HTML proxy module/.test(e.message)) {\n    server.restart() // clear stale proxy map\n  }\n  throw e\n}","preventionTips":["Always pair every emitted ?html-proxy&index=N id with addToHTMLProxyCache.","Restart the dev server after editing inline HTML script/style blocks if proxies look stale.","Avoid multiple plugins rewriting inline HTML in conflicting ways."],"tags":["html","plugin","build","hmr"],"backgroundTag":null,"analyzedSha":"b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab","analyzedAt":"2026-08-11T11:49:19.515Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}