vitejs/vite · error · Error

No matching HTML proxy module found from ${id}

Error message

No matching HTML proxy module found from ${id}

What it means

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.

Source

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

      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 89620f09af)

Solutions

1. Restart the Vite dev server and clear `node_modules/.vite`.
2. Remove custom plugins that generate or import `?html-proxy` ids.
3. Ensure HTML entry files are not deleted/renamed mid-build.
4. Upgrade Vite — proxy indexing bugs are fixed in patch releases.

try {
  await load(id);
} catch (e) {
  if (/No matching HTML proxy module found/.test(e.message)) {
    console.warn('Stale HTML proxy — restart Vite and clear .vite cache');
  }
  throw e;
}

When it happens

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

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

Related errors

• HTML proxy index in "${id}" not found
• No corresponding modern polyfill chunk found for ${htmlFilen
• No corresponding legacy polyfill chunk found for ${htmlFilen
• No corresponding legacy entry chunk found for ${htmlFilename
• 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/08b470944810b3a6.json. Report an issue: GitHub.