A Vite single page app shows 404 when you refresh a route on the live site
404 Not Found when you refresh /about or open a deep linkShort 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.
Fix it fast
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 preview2Match what you see, then jump to its fix
- 1
Netlify shows its own Page not found for any route except /The host has no rewrite to index.html (Netlify)Fix - 2
Firebase Hosting returns 404 for any route except /The host has no rewrite to index.html (Firebase Hosting)Fix - 3
Assets such as /assets/index-xxxx.js return 404, usually on GitHub Pages project sitesThe base path does not match where the site is servedFix
- 1
What does the error look like?
404 Not Found when you refresh /about or open a deep linkPage not found (Netlify) on a route that works inside the appHome 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.toml2Fix
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 2003Verify
Redeploy, then refresh a deep route on the live site.
curl -I https://example.com/aboutConfirmed by docs.netlify.com
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.json2Fix
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/aboutConfirmed by vite.dev
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 previewConfirmed by vite.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Web apps
Attempted import error: firebase/app has no default export
Attempted import error: 'firebase/app' does not contain a default export (imported as 'firebase').
Since the modular SDK (version 9), firebase/app no longer exports one firebase object.
3 causes, each with a fixWeb apps
Firebase Messaging cannot register its default service worker
messaging/failed-service-worker-registration
Firebase Messaging registers a file called firebase-messaging-sw.js from the root of your domain.
3 causes, each with a fixWeb apps
Firestore addDoc throws on a field whose value is undefined
FirebaseError: Function addDoc() called with invalid data. Unsupported field value
Firestore has no undefined type.
2 causes, each with a fixWeb apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 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 fix