Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Vite production build loads a blank page with 404s on its files

ErrorGET 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.

  • Applies to Vite 7, Vite 8, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.html
  2. 2Match what you see, then jump to its fix

    1. 1dist/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. 2The main bundle loads but one image or fetch still returns 404Some URLs are written by hand and ignore baseFix
    3. 3The same build is copied to different paths or opened from an embedded locationThe final folder is unknown at build timeFix

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.html

Confirmed by vite.dev

Did this fix it?

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" src

2Fix

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 preview

Confirmed by vite.dev

Did this fix it?

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 preview

Confirmed by vite.dev

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.