You opened dist/index.html from disk
This is the most common one, and it is two problems stacked.
1. Absolute asset paths. By default Vite writes
<script type="module" crossorigin src="/assets/index-B4x9kQ2.js"></script>
On a web server /assets/… means "from the site root". On a file:/// page
it means the root of your disk — C:\assets\ or /assets/ — so every file
is ERR_FILE_NOT_FOUND.
2. Module scripts use CORS. Change the base to relative paths:
// vite.config.js
export default { base: "./" };
and the paths now resolve — but the entry is still a
<script type="module">. Browsers always fetch modules in CORS mode, and a
file:// page has the opaque origin null, so Chrome and Edge block it:
Access to script at 'file:///…/dist/assets/index-B4x9kQ2.js' from origin
'null' has been blocked by CORS policy
base: './' alone is not enough. Firefox lets a file load modules from the
same folder, which is why "it works on my machine" is sometimes literally
true. The full explanation is in
CORS error from origin 'null'.
Fixes, in order of effort:
Serve it. npx vite preview (after vite build) or
npx serve dist gives the folder a real http://localhost origin.
Fine for you; useless for the person you send it to.
Build one file. vite-plugin-singlefile
inlines every chunk and stylesheet into index.html. An inline module has
nothing to fetch, so the CORS check never runs, and the result opens from
disk, an email attachment or a chat upload:
// vite.config.js
import { viteSingleFile } from "vite-plugin-singlefile";
export default { plugins: [viteSingleFile()] };
Large images and fonts still sit next to it; the free
HTML inliner embeds whatever the plugin left out
and lists anything it couldn't resolve.
Give it a URL. See the last section below.
The site lives under a sub-path
GitHub Pages project sites, GitLab Pages, an S3 prefix and a reverse proxy
at /app/ all serve your build from somewhere other than /. With the
default base: '/' the page asks for https://user.github.io/assets/…
instead of https://user.github.io/repo/assets/…, and gets a 404.
// vite.config.js
export default { base: "/repo/" }; // or "./" if the path isn't fixed
Then tell the router the same thing, or it renders nothing because no route
matches /repo/:
// React Router
<BrowserRouter basename={import.meta.env.BASE_URL}>
// Vue Router
createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes });
import.meta.env.BASE_URL always equals the base you built with, so the
two can't drift. On GitLab Pages, also check that the job publishes
public/ — see GitLab Pages report 404s.
"Expected a JavaScript module script…"
Failed to load module script: Expected a JavaScript module script but the
server responded with a MIME type of "text/html".
The browser asked for a .js file and received an HTML page. Most hosts
configured for single-page apps answer any missing path with
index.html, so a wrong path comes back as a 200 with HTML instead of a 404.
The usual reasons:
- Wrong
base — same as the section above, with a fallback hiding the 404.
- The project root was deployed, not
dist/. The source index.html
points at /src/main.tsx, which only the dev server can compile. Check the
publish directory in Netlify, Vercel, Cloudflare Pages or your CI step.
- A stale
index.html. A CDN or service worker cached the old entry page,
which references hashed files that the new deploy deleted. Hard-reload
(Ctrl+Shift+R); if that fixes it, set Cache-Control: no-cache on
index.html and long caching only on /assets/*.
If the server returns .js with application/octet-stream or text/plain,
the host's MIME table is wrong — the same class of problem as
S3 downloading HTML instead of rendering it.
Refresh or a deep link 404s
The home page loads, links inside the app work, but refreshing /settings
or opening a shared link to it returns 404. The route only exists in
JavaScript; the server looks for a file called settings and has none.
| Host |
Fallback to index.html |
| GitHub Pages |
Copy dist/index.html to dist/404.html in the build step |
| Netlify |
public/_redirects: /* /index.html 200 |
| Vercel |
vercel.json: {"rewrites":[{"source":"/(.*)","destination":"/"}]} |
| Cloudflare Pages |
Automatic when there is no 404.html at the root |
| nginx |
try_files $uri $uri/ /index.html; |
| S3 / static file host |
Error document index.html, or switch to hash routing |
Where you can't configure the server at all, use hash routing
(createHashRouter, createWebHashHistory). URLs look like /#/settings,
the server only ever sees /, and refreshes always work.
An environment variable is undefined
Vite replaces import.meta.env.* at build time, and only for names that
start with VITE_:
import.meta.env.VITE_API_URL; // baked into the bundle
import.meta.env.API_URL; // undefined, always
process.env.API_URL; // ReferenceError: process is not defined
The classic blank page: .env.local exists on your laptop, the CI build
doesn't have it, the value is undefined, and
new URL(import.meta.env.VITE_API_URL) throws before the first render.
Set the variable in the build environment — not the runtime one, there isn't
one — and fail the build early if it's missing:
// vite.config.js
if (!process.env.VITE_API_URL) throw new Error("VITE_API_URL is not set");
process is not defined from a dependency means a package written for
Node expects the global; define: { "process.env": {} } in the config is
the usual stopgap.
Two more that only show up in the build
- Case-sensitive imports.
import Header from "./header" resolves to
Header.tsx on macOS and Windows, then fails on the Linux CI runner. The
build usually errors, but a lazy import() can fail only at runtime.
- A crash during the first render. Without an error boundary, any
exception in a top-level component unmounts the whole tree — white screen.
Run
vite build --mode development --minify false and serve it to get a
readable stack trace.
Stop sending the dist folder
Every file-based fix above has a ceiling: the person you send the build to
still needs the right folder, the right browser and no CORS surprises. A
build preview works best as a URL.
Comma takes the dist/ folder or a zip of it and returns one link. Assets
upload alongside the entry page with their references rewritten, so the
absolute-path and file:// problems disappear, and reviewers comment on the
exact element they mean instead of sending a screenshot. Steps and the API
call for CI are in share a Vite build.
Two honest caveats. Reports run in a sandboxed iframe with scripts enabled
but no same-origin access, so code that touches localStorage or cookies
without a try/catch throws there — guard it. And for path-based routing,
build the preview with hash routing so every view has a working link.
Publish a build preview →
Related