DEV Community

mustafa morbel
mustafa morbel

Posted on Originally published at Medium

Effectively Managing 404 Errors on the Server-Side in React SPAs with Nginx

Originally published on Medium (Medium). Read on Medium for free via Friend Link.

☕ Explore Developer Starter Kits & Guides

Quick Takeaways

  • Stop Masking 404s as 200 OK : Default SPA fallback rules return index.html with a 200 OK status for missing URLs, blinding server monitoring and hurting SEO.
  • Bridge React Router & Nginx : Pair a catch-all client route that redirects to /404 with an Nginx error_page 404 /404 block so the server logs a true 404 while the SPA renders your not-found UI.
  • Track Broken Routes in Logs : Use Nginx access_log and error_log to uncover dead links across React, Vue, or Angular deployments.

Diagram illustrating how a Single Page Application and Nginx coordinate to return real server-side 404 status codes
illustration : Tisna Permadi

Problem Definition

When a user tries to directly access a specific address in an SPA, the server cannot find a matching HTML file for that path and would normally return a 404 error. However, most SPA setups are configured to handle this by returning the application's main index.html instead of a 404 page.

This keeps navigation smooth for the user, but it creates a blind spot for server-side monitoring and error-logging systems. The result? Your server reports a healthy 200 OK response even though the route does not actually exist.

In this article, we will walk through how to effectively manage 404 errors on the server side in your SPAs, broken into four parts: SPA routing basics, React Router catch-all configuration, Nginx redirection, and server-side error tracking.


SPA and Routing: Basic Operation

SPAs provide a seamless experience by dynamically loading all application content through a single HTML page. However, the server's unawareness of client-side routes can lead to silent 404 issues on direct URL access.

Left unhandled, this creates serious problems for server-side error logging, search engine indexing, and user experience. Understanding that gap between client-side routing and server-side responses is the first step toward fixing it.


React Router Configuration for 404 Error Handling

React Router gives us a clean way to catch unknown paths in an SPA. Below is a complete example demonstrating how to configure a catch-all route that renders a dedicated PageNotFound component:

import React from "react";
import { Route, Link, Routes } from "react-router-dom";

export default function App() {
  return (
    <div>
      <nav>
        <ul>
          <li>
            <Link to="/">Home</Link>
          </li>
          <li>
            <Link to="/about">About</Link>
          </li>
          <li>
            {/* Link to catch-all route */}
            <Link to="/does-not-exist">
              Catch all route
            </Link>
          </li>
        </ul>
      </nav>

      <Routes>
        <Route path="/about" element={<About />} />
        <Route path="/" element={<Home />} />

        {/* Match when no other routes match */}
        <Route path="*" element={<PageNotFound />} />
      </Routes>
    </div>
  );
}

function Home() {
  return <h2>Home</h2>;
}

function About() {
  return <h2>About</h2>;
}

function PageNotFound() {
  return (
    <div>
      <h2>404 Page not found</h2>
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

The <Route path="*"> component routes all undefined paths to PageNotFound. When a user enters an invalid URL, they see a clear 404 page inside the app.

However, that alone still leaves the server returning 200 OK. To involve Nginx, using window.location.href = "/404" forces a full browser request so the server sees the /404 path first. We can update the catch-all route as follows:

<Route path="/404" element={<PageNotFound />} />
<Route
  path="*"
  element={() => {
    return <>{(window.location.href = "/404")}</>;
  }}
/>
Enter fullscreen mode Exit fullscreen mode

Once the request hits /404 on the Nginx side, the server can record a genuine 404 status while still serving the SPA bundle so React renders the PageNotFound view.


Nginx Configuration for SPA Redirection

Nginx makes it straightforward to combine SPA fallback routing with proper server-side 404 handling. In the configuration below, normal routes fall back to index.html, while /404 is handled explicitly via error_page:

server {
    listen       80;
    server_name  localhost;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
        try_files $uri $uri/ /index.html;
    }

    error_page 404 /404;

    location = /404 {
        internal;
        root   /usr/share/nginx/html;
        try_files /index.html;
    }
}
Enter fullscreen mode Exit fullscreen mode

In this configuration, try_files tells Nginx to look for the requested URI first, and if no static file exists, to serve index.html. Marking location = /404 as internal ensures it is only triggered through Nginx's internal error handling.


Application for Different Types of SPAs

This same pattern applies to SPAs built with other JavaScript frameworks such as Vue and Angular. While each framework has its own client-side router syntax, the Nginx and container setup stays largely the same: route invalid paths to a dedicated /404 endpoint so the server and browser stay in sync.


Server-Side Tracking of 404 Errors

Once Nginx is aware of 404s, its built-in logging becomes far more useful. The access_log and error_log directives let you see exactly which missing URLs users and crawlers are hitting—giving you concrete data to fix broken links, tighten redirects, and protect your SEO strategy.

How does your team handle server-side 404s in production SPAs — Nginx rules, edge middleware, or SSR? I'd love to hear your thoughts 🧠💬


Keep Exploring

If you found this guide helpful, check out these related React and TypeScript resources:


About the Author

I'm Mustafa Morbel — Senior Frontend Engineer with over 17 years of experience building scalable React architectures, WebGL applications, and resilient web systems.

Top comments (0)