Maaz Zindani

Loading the index…

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

My Vite and React Router site returns 404 on Vercel when I refresh a page

ErrorVercel 404 on page refresh in a Vite React app

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

  • Applies to Vite 6, Vite 7, React Router 7, Vercel
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1Only the root path works, client-side links work, and a refresh gives 404No rewrite sends unknown paths to index.htmlFix
    2. 2vercel.json has cleanUrls set to true and the rewrite still gives 404cleanUrls is on, so the destination with .html does not matchFix
    3. 3Even the root path is 404, or the build log does not mention your app's buildIn a monorepo, Vercel serves the wrong folderFix

What does the error look like?

  • Vercel 404 on page refresh in a Vite React app
  • Deep 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.json

2Fix

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/dashboard

Confirmed by vercel.com

Did this fix it?

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

2Fix

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/dashboard

Confirmed by vercel.com

Did this fix it?

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

2Fix

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/dashboard

Confirmed by vercel.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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