vitejs/vite · error · Error

HTML proxy index in "${id}" not found

Error message

HTML proxy index in "${id}" not found

What it means

Thrown in the CSS `transform` hook when processing an inline-CSS request that is also an HTML proxy module, but the proxy index could not be extracted from the id. The id normally contains an `?html-proxy&index=N` segment parsed by `htmlProxyIndexRE`; if that regex does not match, Vite cannot correlate the CSS back to its originating `<style>` block.

Source

Thrown at packages/vite/src/node/plugins/css.ts:569

          include: CSS_LANGS_RE,
          exclude: [commonjsProxyRE, SPECIAL_QUERY_RE],
        },
      },
      async handler(css, id) {
        css = stripBomTag(css)

        // cache css compile result to map
        // and then use the cache replace inline-style-flag
        // when `generateBundle` in vite:build-html plugin and devHtmlHook
        const inlineCSS = inlineCSSRE.test(id)
        const isHTMLProxy = htmlProxyRE.test(id)
        if (inlineCSS && isHTMLProxy) {
          if (styleAttrRE.test(id)) {
            css = css.replace(/"/g, '"')
          }
          const index = htmlProxyIndexRE.exec(id)?.[1]
          if (index == null) {
            throw new Error(`HTML proxy index in "${id}" not found`)
          }
          addToHTMLProxyTransformResult(
            `${getHash(cleanUrl(id))}_${Number.parseInt(index)}`,
            css,
          )
          return {
            code: `export default ''`,
            map: { mappings: '' },
          }
        }

        const inlined = inlineRE.test(id)
        const modules = cssModulesCache.get(config)!.get(id)

        // #6984, #7552
        // `foo.module.css` => modulesCode
        // `foo.module.css?inline` => cssContent
        const modulesCode =

View on GitHub (pinned to 89620f09af)

Solutions

1. Clear Vite's cache (`node_modules/.vite`) and restart the dev server.
2. Disable custom plugins that rewrite or generate HTML proxy ids to isolate the cause.
3. Upgrade Vite to the latest patch — proxy id formats changed across versions and stale tooling can generate mismatched ids.
4. Report the full `id` from the error message if it recurs, as it indicates a Vite-internal bug.

try {
  await transform();
} catch (e) {
  if (/HTML proxy index .* not found/.test(e.message)) {
    // restart dev server / clear .vite cache
    console.warn('HTML proxy index missing — clearing cache and restarting');
  }
  throw e;
}

When it happens

Trigger: A request id matches both `inlineCSSRE` and `htmlProxyRE` but `htmlProxyIndexRE.exec(id)` returns null (no `&index=` portion present). This usually indicates a malformed proxy id generated internally or an unexpected manual request.

Common situations: This is an internal invariant violation. Most often seen with custom plugins that manipulate HTML proxy ids, with stale HMR module graphs after upgrading Vite, or with hand-crafted requests to the dev server.

Related errors

• No matching HTML proxy module found from ${id}
• base or replace is required
• Unknown lang: ${lang}
• Unsupported dependency type: ${dep.type}
• HMR is not supported by this runner transport, but `hmr` opt

AI-assisted analysis of vitejs/vite@89620f09af (2026-08-03). Data as JSON: /data/errors/c11f4597b49b8b60.json. Report an issue: GitHub.