vitejs/vite · error · Error

No matching HTML proxy module found from

Error message

No matching HTML proxy module found from ${id}

What it means

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.

Solutions

1. Restart the dev server / clear the Vite cache to drop stale proxy ids.
2. If a custom plugin transforms HTML and emits ?html-proxy&index=N ids, ensure it calls addToHTMLProxyCache for every index it produces.
3. Check for duplicate or conflicting HTML-transforming plugins that both rewrite inline scripts.
4. Update Vite and HTML-related plugins to pick up fixes around proxy index consistency.

Example fix

// before — plugin emits proxy id but never registers it
const id = `${file}?html-proxy&index=${i}`
// after
import { addToHTMLProxyCache } from 'vite'
addToHTMLProxyCache(config, url, i, { code, map })

// If you emit proxy ids, validate the index exists before referencing
function safeHtmlProxyLoad(map, url, index) {
  const entry = map.get(url)?.[index]
  if (!entry) throw new Error(`Missing proxy entry for ${url}[${index}]`)
  return entry
}

try {
  return await load(id)
} catch (e) {
  if (/No matching HTML proxy module/.test(e.message)) {
    server.restart() // clear stale proxy map
  }
  throw e
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• " } is not supported for assets in files
• Cannot send non-custom events from the client to the server.
• Cannot send non-custom events from the server to the client.
• Circular worker imports detected. Vite does not support it…
• client ID conflict detected. Please restart the dev server.

AI-assisted analysis of vitejs/vite@b4d66fee14 (2026-08-11). Data as JSON: /api/errors/08b470944810b3a6. Report an issue: GitHub.

Appendix: source

Thrown at packages/vite/src/node/plugins/html.ts:132

      handler(id) {
        return id
      },
    },

    load: {
      filter: { id: isHtmlProxyRE },
      handler(id) {
        const proxyMatch = htmlProxyRE.exec(id)
        if (proxyMatch) {
          const index = Number(proxyMatch[1])
          const file = cleanUrl(id)
          const url = file.replace(normalizePath(config.root), '')
          const result = htmlProxyMap.get(config)!.get(url)?.[index]
          if (result) {
            // set moduleSideEffects to keep the module even if `treeshake.moduleSideEffects=false` is set
            return { ...result, moduleSideEffects: true }
          } else {
            throw new Error(`No matching HTML proxy module found from ${id}`)
          }
        }
      },
    },
  }
}

export function addToHTMLProxyCache(
  config: ResolvedConfig,
  filePath: string,
  index: number,
  result: { code: string; map?: SourceMapInput },
): void {
  if (!htmlProxyMap.get(config)) {
    htmlProxyMap.set(config, new Map())
  }
  if (!htmlProxyMap.get(config)!.get(filePath)) {
    htmlProxyMap.get(config)!.set(filePath, [])

View on GitHub (pinned to b4d66fee14)