Why React Apps Show a 404 on Refresh in Azure Static Web Apps (And How to Fix It)

Single-page React applications hosted on Azure Static Web Apps commonly run into a confusing issue: navigation within the app works perfectly, but refreshing the page or visiting a route directly results in Azure’s generic 404 error page instead of the application. This is a well-known mismatch between client-side routing and static website hosting, and it has a simple, one-file fix.

The cause

A React single-page application (SPA) is built around one physical HTML file: index.html. Routes such as /dashboard or /conversations are not real files on the server. They are virtual paths created and managed entirely in the browser by a React Router configuration, which swaps rendered content after index.html has already loaded.

This works seamlessly during in-app navigation since clicking a link never triggers a new request to the server. Instead, the browser re-renders content using JavaScript already running on the page.

A full-page refresh or direct URL access is different. It sends a brand-new request straight to the server for that exact path. Azure Static Web Apps checks for a matching file, finds nothing at /dashboard (since only index.html exists), and returns a 404 error.

This issue is one of the most common React SPA routing problems developers encounter when deploying applications to Azure.

The fix

Azure Static Web Apps supports a configuration option called navigationFallback, which instructs the server to serve index.html for any route that doesn’t match a real file. This allows the React Router and client-side routing logic to take over and render the correct page.

Create a file named staticwebapp.config.json inside the app’s public directory with the following content:

{
“navigationFallback”: {
“rewrite”: “/index.html”,
“exclude”: [“/static/*”, “/*.png”, “/*.jpg”, “/*.ico”, “/*.json”]
}
}

The exclude array ensures that requests for actual static assets—such as images, icons, and JSON files—are still served normally rather than being redirected to index.html.

Once this file is deployed, any unmatched route is treated as a valid React Router route rather than a missing file. As a result, the application loads correctly on page refresh and direct navigation.

This Azure Static Web Apps routing configuration is the recommended approach for preventing React app 404 errors on refresh.

Why isn’t this a bug

This behavior is not a defect in React, React Router, or Azure. It reflects a fundamental difference between client-side routing and server-side file resolution.

Any static hosting platform—including Azure Static Web Apps, Netlify, GitHub Pages, or AWS S3 with CloudFront—requires a similar route rewriting or fallback configuration. Applications that work during navigation but fail on refresh are almost always missing this setup.

For developers deploying a React app on Azure, configuring navigationFallback is a standard best practice that ensures consistent routing behavior across all URLs.

Summary

• Symptom: 404 error on page refresh or direct URL access in a deployed React application.
• Cause: Client-side routes do not correspond to real server-side files.
• Fix: Add a navigationFallback rule using staticwebapp.config.json to redirect unmatched routes to index.html.
• Scope: Applies to Azure Static Web Apps and other static hosting platforms running a single-page application (SPA).
• Benefit: Eliminates React Router 404 refresh issues and ensures reliable Azure Static Web Apps routing for direct URL access.