Blazor WASM 404 error and fix for GitHub Pages
The project structure of a Blazor WASM project is in some places very different than other frontend frameworks in the .NET stack. One of the nice things about Blazor WASM is that it can be hosted by any static file host. A problem with this is that routing is handled in many different ways on different hosts. In this article, we will look at the
404 error that often occurs when accessing a route directly on a GitHub Pages hosted Blazor WASM page and how to fix it.
Previously we have often used the IIS to host our websites and managed routing and error handling through the
web.config file. We can't do this when using static file hosts. GitHub Pages is not configured to support SPA (Single Page Application) routing out of the box, but we can make some changes to our project to make it work.
First, we need to see when the problem occurs. If we have some Blazor WASM page that is hosted on GitHub Pages that uses routing meaning that it has more than one page. Then we might have an URL like the following:
We can nicely go to this page using the navigation in the website or when we run the project locally. But if we try to access this URL directly we will be faced with the following page.
404 File not found The site configured at this address does not contain the requested file. If this is your site, make sure that the filename case matches the URL. For root URLs (like http://example.com/) you must provide an index.html file.
The problem occurs because of how GitHub Pages serves files. If it sees something that looks like a directory in the URL after the expected
https://myaccount.github.io/MyProject/ then it will assume that you have some folder e.g.
/MyPage that has an
index.html file available to serve. We don't actually have a directory for
/MyPage as it is just a route that we have defined in Blazor to make the experience of using the website better for the user.
The solution consists of two parts. First, we will need to redirect the user to some known page where we can control their further navigation. And then we will need to tell the Blazor WASM website where the user actually wanted to go.
We catch the user by creating a file called
404.html in the
wwwroot folder of the project which is what gets published when using GitHub Pages to host. GitHub Pages automatically redirects users to this page instead of the screen we saw earlier. It shows this page but maintains the same URL which we can then extract and use to recover the state. The content of the
404.html is the following:
This comes from the GitHub repository https://github.com/rafgraph/spa-github-pages which is a repository that contains some general useful files for using SPA frameworks on GitHub Pages.
Now we have been redirected to the
index.html file and all paths, query strings, and hashtags (anchor links) have been passed on. The query strings are combined in a single query string called
q and the paths are placed in a query string called
We then need to decode these query strings and navigate to the correct page. This is done with the following code snippet that we will need to place in the head of our
index.html file (the earlier the better).
It navigates to the correct page by setting the state directly using the
window.history.replaceState API. This sets the state that Blazor WASM uses internally to keep track of which page you are on.
Now we have seen when the 404 error happens in a Blazor WASM project hosted on GitHub Pages. We have explored why it happens. And in the end, we have seen a solution for the problem which it shares with other SPA frameworks on GitHub Pages.
If you have any questions about the content of this article or comments then feel free to reach out.
elmah.io: Error logging and Uptime Monitoring for your web apps