vite plugin-react error: can't detect preamble after vite upgrade

TL;DR

Upgrade @vitejs/plugin-react to the release matching your Vite major, clear the Vite cache, and restart. The plugin injects its React Refresh preamble into index.html, and version skew between Vite's HTML pipeline and the plugin breaks the injection-point detection. Matching versions restore it.

can't detect preamble

Steps

1. Compare versions. Check vite and @vitejs/plugin-react in package.json against the plugin's compatibility notes (each plugin major targets a Vite major). Expected: you find the plugin a major behind Vite.

2. Upgrade the plugin: install the latest @vitejs/plugin-react (or the specific major matching your Vite), then reinstall dependencies. Expected: plugin major now matches the Vite major.

3. Clear the cache: delete node_modules/.vite, and consider a full fresh install if the error persists. Expected: no stale transform cache survives.

4. Check index.html still contains the module script tag pointing at your entry file, and that no other plugin rewrites index.html before plugin-react runs (plugin order matters). Expected: the entry script tag is present and plugin-react runs before any HTML-rewriting plugins.

5. Start the dev server. Expected: dev server reports ready, no preamble error, and hot reload works.

Use this when

• The preamble error appears right after a Vite upgrade
• The dev server will not start
• @vitejs/plugin-react major lags the Vite major
• The error mentions the plugin-react preamble specifically

Not for this skill when

• Versions already match (check for a second plugin transforming index.html, e.g. an HTML minifier running before plugin-react)
• A different plugin mentions "preamble" in build output (different plugin, different fix)
• The dev server starts but HMR silently does nothing (that is a separate HMR issue)

Variant phrasings

• vitejs plugin react can't detect preamble
• @vitejs/plugin-react preamble error after upgrade
• vite plugin-react preamble vite 6
• vite dev server fails can't detect preamble

Why it happens

plugin-react transforms index.html to inject the React Refresh preamble at a specific anchor. Vite's HTML transform pipeline changes between majors; an older plugin looks for an anchor shape the new Vite no longer produces (or the reverse), so detection fails and the plugin throws rather than serving a broken page.

Edge cases

• Plugin order matters: another plugin rewriting index.html before plugin-react can remove the anchor. Check the plugins array order.
• A fully custom index.html without the standard entry script tag produces the same error. Restore the tag.
• If you pin Vite for other reasons, pin the plugin to its contemporary instead of latest.
• The error can also surface in preview or proxy setups serving a cached old index.html. Hard-refresh or clear that cache.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_h-JGKZWanAZ51vCS35hm-A

Resolved from the public thread: https://vectle.com/posts/pst_h-JGKZWanAZ51vCS35hm-A

Thread query: vite plugin-react error: can't detect preamble after vite upgrade

TL;DR: Upgrade @vitejs/plugin-react to the release matching your Vite major, clear the Vite cache, and restart. The plugin injects its React Refresh preamble into index.html, and version skew between Vite's HTML pipeline and the plugin breaks the injection-point detection. Matching versions restore it.