Custom 404 error page, Hugo and Azure Static Web Apps

In this blog post I will show you how to configure custom 404 error page, for a Hugo site hosted in Azure Static Web Apps. (In case you don’t know what 404 (Not Found) error is, it’s an HTTP status code which means that the page you were trying to reach on a website couldn’t be found on the server, altough the server itself is reachable.)

As I have previously blogged, building4.cloud static web site is generated by Hugo, which by default creates 404 error page in the root of the website (such as https://building4.cloud/404.html). Azure Static Web Apps does not by default try to serve 404 NotFound page from the root path. And if by accident you happen to end up visiting a non-existing page, you’ll be presented Microsoft’s default 404 error page, like the one seen below.

If you’re happy with the default error page, you don’t need to do anything. But if you’re like me, you’ll want to change that. Answer being routes in Azure Static Web Apps.

What are routes in Azure Static Web Apps?

Microsoft’s documentation defines routing as follows:
Routing in Azure Static Web Apps defines back-end routing rules and authorization behavior for both static content and APIs. The rules are defined as an array of rules in the routes.json file.

This means that we can use routes.json file to modify default behaviour. The file needs to be located in the root of app’s build artifact folder. In Hugo’s case routes.json file needs to be created in static -folder. As the rules are defined in an array, it’s possible to enter multiple rules in the same file. It’s also worth mentioning that rules are executed in the order as they appear in the array and rule evaluation stops at the first match. It’s not possible to chain routing rules together.

In my case I’m only interested in overriding default behaviour for custom 404 Not Found error page, and for that I need to use platformErrorOverrides array. It would also be possible to use same array for other HTTP status codes, for example 401 (Unauthorized) or 302 (Unauthenticated).

The solution

As explained previously we can use a simple routes.json file to override default 404 NotFoud behaviour. And here is the content of routes.json file that we need to store in Hugo’s static -folder:

{
    "platformErrorOverrides": [
        {
        "errorType": "NotFound",
        "serve": "/404.html"
        }
    ]
}

I also need to create my custom 404.html page. After creating the page all that’s left to do is, git add, git commit and git push to get GitHub Actions to kickoff build and deploy. After that’s done, I can now visit a non-existing page such as https://building4.cloud/non-existing-page, and see that my custom error page is correctly served.

Yes, I know it’s not much nicer than the default page 😄. Maybe I’ll update it some time later.

Want to know more or leave a comment? Did I miss something? Reach out to me on LinkedIn or Twitter.

Until next time.