Custom 404 page for a static website


At the moment, does not have the ability to define custom error pages. For a normal web application, you would generally already handle this in the app. But for a static website, this is not the case.


There is a way you can make it work, but it’s considered a hack. This is not officially supported but is documented here to be used as an example of what is possible.


  • You have an existing project set up and know how to tweak your file
  • It assumes you are running a PHP container, or know how to tweak the proposed script to your preferred language.


We will be using the passthru element in web-locations.


passthru: Whether to forward disallowed and missing resources from this location to the application and can be true, false or an absolute URI path (with leading /). The default value is false. For non-PHP applications it will generally be just true or false. In a PHP application this will typically be the front controller such as /index.php or /app.php. This entry works similar to mod_rewrite under Apache. Note: If the value of passthru does not begin with the same value as the location key it is under, the passthru may evaluate to another entry. That may be useful when you want different cache settings for different paths, for instance, but want missing files in all of them to map back to the same front controller. See the example block below.

What the above means is that we can define a passthru for any file that does not exist (i.e.: is not a static file, or is non existent), and we can then pipe all requests to a special PHP file that shows a 404.

Create a special PHP file.

Create a file called custom_404.php and put it in the root of your project. This script will be called by passthru. It can contain anything you want, but make sure it responds with a 404 Not Found header. This makes sure that search engine bots know that certain pages don’t exist.

Example custom_404.php:

header("HTTP/1.0 404 Not Found"); //IMPORTANT: we need to return the correct HTTP status code.
        /* simple styling to center the text vertically and horizontally */
        html, body, .container {
            height: 100%;
        .container {
            display: -webkit-flexbox;
            display: -ms-flexbox;
            display: -webkit-flex;
            display: flex;
            -webkit-flex-align: center;
            -ms-flex-align: center;
            -webkit-align-items: center;
            align-items: center;
            justify-content: center;
    <div class="container"> 
      <p>Hi there, it looks like we can't find the page you are looking.</p>
      <p class="suggestions">
        Add logic here that uses the PHP $_SERVER variable 
        to determine the user intent and display some suggestions
      <p>Want to <a href="/">go back to the home page?</a></p>

Point passthru to custom_404.php

Now open up and edit your web.locations so that the passthru points to the correct location.

            # The public directory of the application relative to its root.
            root: 'public'
            index: ['index.html']
            scripts: false
            allow: true
            expires: 1d
            passthru: "/custom_404.php"

Note: Make sure you remove the web.commands.start from your configuration, if it’s still there the php script cannot run.

1 Like