My Vite and React Router site returns 404 on Vercel when I refresh a page
Vercel 404 on page refresh in a Vite React appShort answer
Vercel serves files. A deep link such as /dashboard has no file, so it returns 404 until you rewrite every path to index.html. Add one rewrite in vercel.json. In a monorepo, make sure Root Directory and Output Directory point at the Vite app.
Fix it fast
1Find out which cause you have
Open the deep link in a private window. If the home page loads and the deep link is 404, the app is missing the rewrite. If both fail, the output folder is wrong.
curl -I https://your-app.vercel.app/ curl -I https://your-app.vercel.app/dashboard2Match what you see, then jump to its fix
- 1
Only the root path works, client-side links work, and a refresh gives 404No rewrite sends unknown paths to index.htmlFix - 2
vercel.json has cleanUrls set to true and the rewrite still gives 404cleanUrls is on, so the destination with .html does not matchFix - 3
Even the root path is 404, or the build log does not mention your app's buildIn a monorepo, Vercel serves the wrong folderFix
- 1
What does the error look like?
Vercel 404 on page refresh in a Vite React appDeep link returns 404 but the home page works
Cause 1 of 3
No rewrite sends unknown paths to index.html
1Check
Vite documents that deep linking does not work out of the box for a single page app. Check that vercel.json exists at the root of the project.
cat vercel.json2Fix
Create vercel.json with the catch-all rewrite.
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}3Verify
Redeploy and request the deep link.
curl -I https://your-app.vercel.app/dashboardConfirmed by vercel.com
Cause 2 of 3
cleanUrls is on, so the destination with .html does not match
1Check
With cleanUrls true, paths drop the file extension. Look for the setting.
grep -n cleanUrls vercel.json2Fix
Write the destination without the extension.
{
"cleanUrls": true,
"rewrites": [
{ "source": "/(.*)", "destination": "/" }
]
}3Verify
Redeploy and reload the deep link.
curl -I https://your-app.vercel.app/dashboardConfirmed by vercel.com
Cause 3 of 3
In a monorepo, Vercel serves the wrong folder
1Check
Only the contents of the Output Directory are served. Root Directory decides where the build runs. In a repository with several packages, both must point at the Vite app.
ls apps/web/dist/index.html
grep -n outputDirectory vercel.json2Fix
Set Root Directory to the app folder in Project Settings. If you override the output folder, use outputDirectory in that app's vercel.json.
{
"outputDirectory": "dist",
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}3Verify
Redeploy. The root path and the deep link both return 200.
curl -I https://your-app.vercel.app/dashboardConfirmed by vercel.com
How do I stop it coming back?
- Add the rewrite the first time you deploy a router-based SPA.
- Keep one vercel.json per deployed app, in that app's root directory.
- Open one deep link after every deploy as a smoke test.
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.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web 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 fixWeb apps
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fixWeb apps
axios gets 429 Too Many Requests from a React app
429 (Too Many Requests)
A 429 comes from the server or an API gateway, not from axios: your client sent too many requests in a window.
4 causes, each with a fixWeb apps
Axios request is not cancelled when a React component unmounts
A cancelled request is logged as an error in the catch block
Axios cancels a request when you pass it an AbortSignal and later call abort() on its controller.
4 causes, each with a fix