Maaz Zindani

Loading the index…

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

A Vite single page app shows 404 when you refresh a route on the live site

Error404 Not Found when you refresh /about or open a deep link

Short answer

Client side routes like /dashboard are not real files in dist. The host looks for them, finds nothing and returns 404. Tell the host to answer every path with index.html, and make sure the Vite base setting matches the folder the site is served from.

  • Applies to Vite 7, React Router 7, Netlify, Firebase Hosting
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Serve the build locally. If a refresh on a deep route works here but not on the host, the host needs a rewrite rule.

    npm run build
    npx vite preview
  2. 2Match what you see, then jump to its fix

    1. 1Netlify shows its own Page not found for any route except /The host has no rewrite to index.html (Netlify)Fix
    2. 2Firebase Hosting returns 404 for any route except /The host has no rewrite to index.html (Firebase Hosting)Fix
    3. 3Assets such as /assets/index-xxxx.js return 404, usually on GitHub Pages project sitesThe base path does not match where the site is servedFix

What does the error look like?

  • 404 Not Found when you refresh /about or open a deep link
  • Page not found (Netlify) on a route that works inside the app
  • Home page loads but assets return 404 under a sub path

Cause 1 of 3

The host has no rewrite to index.html (Netlify)

1Check

Look for a _redirects file in the folder that gets published (in a Vite app it ends up in dist), or a redirects block in netlify.toml.

ls dist/_redirects
grep -n "redirects" netlify.toml

2Fix

Add a rewrite with status 200 so every path returns index.html. Put the file in the public/ folder: Vite copies that folder into the dist root unchanged on every build.

# public/_redirects
/*  /index.html  200

3Verify

Redeploy, then refresh a deep route on the live site.

curl -I https://example.com/about

Confirmed by docs.netlify.com

Did this fix it?

Cause 2 of 3

The host has no rewrite to index.html (Firebase Hosting)

1Check

Open firebase.json and look for a rewrites entry under hosting.

grep -n -A4 rewrites firebase.json

2Fix

Point the public folder at dist and rewrite every path to /index.html.

{
  "hosting": {
    "public": "dist",
    "rewrites": [
      { "source": "**", "destination": "/index.html" }
    ]
  }
}

3Verify

Deploy, then request a deep link directly.

curl -I https://example.com/about

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The base path does not match where the site is served

1Check

A project site lives at https://USERNAME.github.io/REPO/, so built URLs must start with /REPO/. Check for base in the config.

grep -n "base" vite.config.*

2Fix

Set base to the repository name with slashes on both sides. For a user site or a custom domain, leave it at the default.

// vite.config.js
export default defineConfig({
  base: '/my-repo/',
})

3Verify

Rebuild and preview it; the assets should now load from the sub path.

npm run build
npx vite preview

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Add the rewrite rule to the repository, not only to the host dashboard, so a new site gets it too.
  • Test every deploy with a refresh on a deep link, not only a click from the home page.
  • Use vite preview as a first check, but remember it is not a production server.

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

Next step

Want this handled for good?

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