DEV Community

linkbruno.com
linkbruno.com

Posted on

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 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;
}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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" }] }
Enter fullscreen mode Exit fullscreen mode

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.js should be a real 404, not index.html served as JavaScript (which produces a confusing "Unexpected token '<'" error). With Nginx, add a separate location /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
Enter fullscreen mode Exit fullscreen mode

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

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.

Top comments (0)