Maaz Zindani

Loading the index…

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

React Router routes return 404 or a blank page on GitHub Pages

Error404 on refresh at a path such as /about

Short answer

GitHub Pages serves files, so a deep link such as /about has no file and returns 404 before React Router runs. Use HashRouter, which keeps the route in the URL hash and never sends it to the server. A blank page on a project site is a different cause: the Vite base and the router basename must be /repo-name/.

  • Applies to React Router 7, Vite 7, GitHub Pages
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the browser network tab on the failing page. A 404 on the page URL itself means the server has no such file (cause 1). A 404 on /assets/... means the app was built for the wrong base path (cause 2).

    curl -I https://USER.github.io/REPO/about
  2. 2Match what you see, then jump to its fix

    1. 1The home page works, links inside the app work, but refresh or a pasted link to /about returns 404A path URL is refreshed or opened directlyFix
    2. 2Blank page, and the JS and CSS requests go to /assets/... and return 404The app is built for the site root but served from /REPO/Fix

What does the error look like?

  • 404 on refresh at a path such as /about
  • Blank page on https://user.github.io/repo-name/ and 404 for the JS and CSS files in the browser network tab

Cause 1 of 2

A path URL is refreshed or opened directly

1Check

BrowserRouter uses real paths, but GitHub Pages only serves files that exist in the published folder. Nothing exists at /about.

curl -s -o /dev/null -w '%{http_code}\n' https://USER.github.io/REPO/about

2Fix

Switch to HashRouter. It stores the location in the URL hash, so the server never receives the route.

import { HashRouter, Routes, Route } from "react-router";

<HashRouter>
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="/about" element={<About />} />
  </Routes>
</HashRouter>
// URLs look like https://USER.github.io/REPO/#/about

3Verify

Open the /#/about URL in a new tab and refresh. The page loads.

curl -I https://USER.github.io/REPO/

Confirmed by reactrouter.com

Did this fix it?

Cause 2 of 2

The app is built for the site root but served from /REPO/

1Check

A project site lives at https://USER.github.io/REPO/. Vite's base defaults to /, so built asset URLs point at the domain root.

grep -n 'base' vite.config.*

2Fix

Set base to the repository path in vite.config, and give the router the same basename if you use BrowserRouter.

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

// BrowserRouter only
<BrowserRouter basename="/REPO">

3Verify

Rebuild, deploy and reload. Assets load with status 200 under /REPO/assets/.

npm run build

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Decide early: a user site or custom domain can keep base at /, a project site needs /REPO/.
  • Deploy through the GitHub Actions workflow from the Vite docs so the build always runs with the right base.

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.