How to fix 404 on refresh in a single-page app (React Router, Vue Router, Angular) on Nginx, Netlify, Vercel, S3 and GitHub Pages
Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com You build a single-page app with client-side routing. Locally, everything works. You deploy it, click from the homepage t
Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com
You build a single-page app with client-side routing. Locally, everything works. You deploy it, click from the homepage to /settings/profile, and that works too. Then you press refresh, or paste the URL into a new tab, or a colleague opens a link you sent them, and the server says 404 Not Found.
This is one of the most common deployment bugs for React, Vue, Angular and Svelte apps, and every shared link to your app is broken until it's fixed.
Why it happens
When you click a link inside the app, the router changes the URL with the History API (history.pushState) and renders the new view in JavaScript. No request goes to the server.
When you refresh or open the URL directly, the browser does what browsers always do: it asks the server for /settings/profile. The server looks for a file at that path, doesn't find one (your build only has index.html and some assets), and returns 404.
The fix is a fallback rule: for any path that isn't a real file, serve index.html, and let the router take over. The details depend on your host.
Nginx
location / {
root /var/www/app;
try_files $uri $uri/ /index.html;
}
try_files checks for a real file, then a directory, then falls back to index.html. If the app lives under a subpath, scope it:
location /app/ {
alias /var/www/app/;
try_files $uri $uri/ /app/index.html;
}
And make sure the router knows about the subpath (basename in React Router, base in Vue Router's createWebHistory('/app/'), <base href="/app/"> in Angular).
Apache
FallbackResource /index.html
in the virtual host or .htaccess. Older guides use a mod_rewrite block; FallbackResource does the same thing in one line.
Netlify
A _redirects file in the publish folder:
/* /index.html 200
The 200 makes it a rewrite rather than a redirect, so the URL in the browser stays the same. Netlify applies this only when no real file matches, so assets are still served normally.
Vercel
For a plain SPA (not Next.js), add a rewrite in vercel.json:
{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }
Framework presets often configure this for you; check before adding a second rule.
Cloudflare Pages
Pages treats a project without a top-level 404.html as a single-page app and serves index.html for unknown paths automatically. If you added a 404.html, that behaviour turns off, and you need a _redirects rule like Netlify's.
S3 and CloudFront
S3 static website hosting lets you set the error document to index.html, but the response still carries a 404 status. With CloudFront in front, the usual fix is a custom error response that maps 403 and 404 from the origin to /index.html with response code 200. That works, but it also turns every genuinely missing file into a 200, which leads to the problem below.
GitHub Pages
GitHub Pages has no rewrite rules. The common workarounds are copying index.html to 404.html (which serves the app, but with a 404 status) or using hash routing (/#/settings/profile), which never asks the server for the path at all. For a public site that should be indexed, a host with real rewrites is a better fit.
Once every path serves the app, a link checker that only reads status codes thinks every URL works. linkbruno.com checks your links on a schedule, and it's worth pairing that with an app that returns a real 404 for unknown routes, so dead links can still be found.
The catch: soft 404s
A blanket fallback fixes refreshes, and creates a new problem: every URL now returns 200, including /this-page-never-existed and /old-feature-we-deleted. To browsers, crawlers and link checkers, your site has infinitely many working pages. That's a soft 404, and it hides every real broken link.
Ways to deal with it:
-
Exclude asset paths from the fallback. A missing
/assets/app.abc123.jsshould be a real 404, notindex.htmlserved as JavaScript (which produces a confusing "Unexpected token '<'" error). With Nginx, add a separatelocation /assets/ { try_files $uri =404; }. -
Render a proper not-found view in the router for unknown routes, with
<meta name="robots" content="noindex">. - Return a real 404 status where you can. With server-side rendering or edge functions, check the route against a list of known patterns and set the status code. For static SPAs you can't change the status per route, which is one of the real reasons to consider pre-rendering for public pages.
Test it
Three requests tell you whether the fix works:
curl -s -o /dev/null -w '%{http_code}\n' https://app.example.com/settings/profile # expect 200
curl -s -o /dev/null -w '%{http_code}\n' https://app.example.com/assets/missing.js # expect 404
curl -s -I https://app.example.com/settings/profile | grep -i content-type # expect text/html
Then test it in a browser by opening a deep link in a fresh tab, not by clicking from the homepage, which never touches the server.
What about hash routing?
Hash routing (createWebHashHistory in Vue Router, HashRouter in React Router) avoids the whole problem: everything after # stays in the browser, so the server only ever sees /. It works on any static host with zero configuration. The trade-offs are ugly URLs, links that most crawlers treat as a single page, and a migration headache later: switching from /#/settings to /settings breaks every shared link unless the app reads the old hash on load and rewrites it. For an internal tool, hash routing is fine. For anything public, set up the fallback rule instead.
Related reading
- Case study (hypothetical): after the domain change, every paying customer landed on a 404
- Soft 404s: your 'page not found' returns 200, and your link checker thinks it's fine
- ERR_TOO_MANY_REDIRECTS: the 6 configs that cause redirect loops and how to find them
- Anchor link not working? How to find and fix broken #section links
- How to find broken links with Playwright (a test you can drop into CI)
Which host gave you the most trouble with SPA fallbacks? For me it was CloudFront, where the fix for refreshes quietly turned every missing asset into a 200.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.