Hello guys, you’ve just finished building a beautiful Single Page Application (SPA) maybe using React, Vue, or Blazor. You deploy it to Azure Static Web Apps, everything looks perfect, and your homepage loads like a dream.
Then, you click a link to /dashboard, and it works. But the moment you hit Refresh or try to share that link with a teammate?
404: Not Found
It’s frustrating, it’s common, and fortunately, it’s a five-minute fix. Here is why it happens and how to fix the issue.
Why is this happening?
In a modern SPA, “routing” is handled by the browser, not the server. When you click on a link, your JavaScript framework intercepts the click and updates the URL without actually requesting a new page from Azure.
However, when you refresh the page at mywebapp.com/reports, your browser sends a literal request to the Azure server looking for a file named reports (or a folder with an index.html inside it).
Since your build only produced one index.html file at the root, Azure looks around, finds nothing at that path, and throws a 404.
The Solution: The staticwebapp.config.json File
To fix this, we need to tell Azure buddy: “Hey you Microsoft Azure, if you don’t find a specific file, just serve the main index.html and let the app handle the rest.” This is called a Navigation Fallback.
Step 1: Create the Config File
In the root of your project’s source code (the same folder as your package.json or your project file), create a new file named:staticwebapp.config.json
Step 2: Add the Fallback RulePaste the following configuration into that file:
{
"navigationFallback": {
"rewrite": "/index.html",
"exclude": ["/static/images/*.{png,jpg,gif}", "/css/*"]
}
}
rewrite: This tells Azure to serve your main index.html whenever a request doesn’t match a physical file.
exclude: This is important! It prevents Azure from trying to serve your HTML when a legitimate image or stylesheet is actually missing.
Step 3: Ensure it’s in your Build Output
This is the most common reason the fix “fails.” You must ensure this JSON file is copied to your output/build folder (e.g., dist, build, or wwwroot) during the deployment process.
For React/Vue: Place the file in your public folder.
For Blazor WASM: Place it in your wwwroot folder.
For Vanilla JS: Just keep it in the root.
Verifying the FixOnce you commit and push these changes, wait for your GitHub Action or Azure DevOps pipeline to finish.
Navigate to your app.Go to a deep link (e.g., /settings or /profile).Hard Refresh (Ctrl + F5).
The 404 should disappear, and your app should load the correct route instantly.
Are you seeing this error on a specific framework like Blazor or Angular, or did the config file solve it for you? Commet below, I will check your comments.
For more blogposts, visit Cloudnerchuko.in