React Router routes return 404 or a blank page on GitHub Pages
404 on refresh at a path such as /aboutShort 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/.
Fix it fast
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/about2Match what you see, then jump to its fix
What does the error look like?
404 on refresh at a path such as /aboutBlank 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/about2Fix
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/#/about3Verify
Open the /#/about URL in a new tab and refresh. The page loads.
curl -I https://USER.github.io/REPO/Confirmed by reactrouter.com
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 buildConfirmed by vite.dev
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:
- 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