Handling 404: Page not found error in Flutter

Flutter has released web support that allows you to create dynamic websites. Flutter supports handling any error that might come from web usage such as 404 errors. But, how do you make a custom 404 page for your Flutter application?

This article describes how to create custom pages that are shown anytime a user navigates to a page that doesn’t exist.

How to redirect clients to a custom 404 page in Flutter

Everyone has encountered a “404: Page not found error” when browsing the internet. Flutter handles this issue by automatically redirecting you to the initial route. This is usually the home page of your application. But what if you want to have a fancy 404 page like the ones at AirBnb, GitHub, or even the Flutter website? You can do this easily with Flutter.

To create a custom 404 page, your application needs to use the MaterialApp, CupertinoApp, or WidgetsApp widget. Most applications use one of these three widgets; it is the first widget you call when creating a Flutter application.

The MaterialApp configures the top-level Navigator to search for routes in the following order:

1. For the / route, the home property, if non-null, is used.
2. Otherwise, the routes table is used, if it has an entry for the route.
3. Otherwise, onGenerateRoute is called, if provided. It should return a non-null value for any valid route not handled by home and routes.
4. Finally if all else fails onUnknownRoute is called.

If your route isn’t handled in any of these tables then it uses the onUnknownRoute property to handle your navigation. This callback is typically used for error handling. For example, this function might always generate a “not found” page that describes the route that wasn’t found. Unknown routes can arise either from errors in the app or from external requests to push routes, such as from Android intents.

The following example code demonstrates how to define an anonymous function for the onUnknownRoute property, which takes a RouteFactory, a factory method that takes a RouteSettings function as input and returns a Route. The following snippet shows how simple it can be to define the onUnknownRoute property:

onUnknownRoute: (settings) {
  return MaterialPageRoute(builder: (_) => PageNotFound());
},

PageNotFound is a custom widget that creates the 404 page . This page might explain what happened and redirect the user to the home page, but you can be as creative as you want when creating your 404 your page.

Closing Remarks

When creating a Flutter application it is important to handle any issues that might arise. Using the onUnknownRoute property within MaterialApp, CupertinoApp, or WidgetApp lets you handle the inevitable “page not found” errors in your website.

To learn more about routes in Flutter, see the Medium post “Navigating URLs using named routes”.

About the author: Jose recently graduated from university and now works on Material, a design system that helps teams build high-quality digital experiences. Jose’s team maintains the Flutter material library. To learn more, visit his Jose’s pages on GitHub, LinkedIn, YouTube, and Instagram.