Vite production build loads a blank page with 404s on its files
GET https://example.com/assets/index-<hash>.js 404 (Not Found)Short answer
Vite writes asset URLs that start at the site root unless told otherwise. When the build is served from a subfolder, such as a GitHub Pages project site, those URLs miss the folder and return 404. Set base to the subfolder, or to ./, build again, and check the output with vite preview before deploying.
Fix it fast
1Find out which cause you have
Open the deployed page, DevTools, Network tab, and read the full URL of the first request that returned 404. Compare it with the address the site is really served from.
npm run build grep -o 'src="[^"]*"' dist/index.html2Match what you see, then jump to its fix
- 1
dist/index.html has src="/assets/..." and the site is served from https://host/<folder>/The site lives in a subfolder but base is still /Fix - 2
The main bundle loads but one image or fetch still returns 404Some URLs are written by hand and ignore baseFix - 3
The same build is copied to different paths or opened from an embedded locationThe final folder is unknown at build timeFix
- 1
What does the error look like?
GET https://example.com/assets/index-<hash>.js 404 (Not Found)Blank page after deploy; the console lists failed requests for /assets/...
Cause 1 of 3
The site lives in a subfolder but base is still /
1Check
base defaults to /, so the generated script and stylesheet URLs start at the host root. For GitHub Pages at https://<USERNAME>.github.io/<REPO>/ the docs tell you to set base to '/<REPO>/'.
grep -n "base" vite.config.*2Fix
Set base to the folder, with a leading and a trailing slash, and rebuild. You can also pass it on the command line.
// vite.config.js
export default defineConfig({
base: '/my-repo/',
})
# or
npx vite build --base=/my-repo/3Verify
Look at the built HTML; the URLs now start with the folder.
grep -o 'src="[^"]*"' dist/index.htmlConfirmed by vite.dev
Cause 2 of 3
Some URLs are written by hand and ignore base
1Check
Vite rewrites url() in CSS and references in HTML to follow base. A string path built in JavaScript is not rewritten, so it keeps pointing at /.
grep -rn "'/images\|\"/images" src2Fix
Build such URLs from import.meta.env.BASE_URL, written exactly like that because Vite replaces it at build time.
const logo = `${import.meta.env.BASE_URL}images/logo.png`;3Verify
Rebuild, preview, and open the page with the Network tab filtered to errors.
npm run build
npm run previewConfirmed by vite.dev
Cause 3 of 3
The final folder is unknown at build time
1Check
The docs allow an empty string or ./ as base for this case. Generated URLs then become relative to each file.
grep -n "base" vite.config.*2Fix
Use a relative base. This needs import.meta support in the browser, which the legacy plugin covers for older ones.
export default defineConfig({
base: './',
})3Verify
Serve dist from a different folder with vite preview or any static server and reload.
npm run previewConfirmed by vite.dev
How do I stop it coming back?
- Run npm run preview after every build; it serves dist on port 4173 by default.
- Put the deployed path in one place, the base option, and read it from import.meta.env.BASE_URL in code.
- Do not open dist/index.html from the file system; serve it over HTTP.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
My Vite and React Router site returns 404 on Vercel when I refresh a page
Deep link returns 404 but the home page works
Vercel serves files.
3 causes, each with a fixWeb apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fix