ScaleScaleScaleScale

Tips / Nginx


Creating custom error pages for Nginx on CentOS 7

Custom error pages are something overlooked by developers most of the time. When you are building a website, of course you are going to focus on building your product and company pages, but it’s not a good idea to forget about error pages like 404, 403, 500. Sometimes your visitors see some warnings like:

404 - Not found
403 - Forbidden
500 - Internal Server Error

And what does this 404, 403 and 500 really mean after all? Maybe you or your sysadmins know what is to get a 404 error page, but most of your non technical visitors may not.

Explaining the meaning of this errors and adding a way to report the problem to you will help you to avoid server side and site programming issues, it can even help you to minimize errors and help your sales to grow when you have important bugs or critical errors.

Today we will learn how to create custom error pages for Nginx web server. Let’s start with the fun stuff.

How to create custom error pages for Nginx

Before we start:

  • We will assume you have Nginx installed and working on your production/testing enviroment.
  • The custom error pages you will see here will be only as an example, you can tweak the messages, graphic design and style to match your current website design.

Creating a 404 custom error page

touch /usr/share/nginx/html/my_custom_404_error.html
nano -w /usr/share/nginx/html/my_custom_404_error.html

Let’s add some custom message to that file, example:

<h1 color='red'>Error 404: What you are looking can not be found at this time</h1>
<p>Try hitting the back button on your browser and try again.</p>
<p>If this happens more than 1 time, please report the error emailing us at support@yoursite.com</p>

Creating a 403 custom error page

touch /usr/share/nginx/html/my_custom_403_error.html
nano -w /usr/share/nginx/html/my_custom_403_error.html

Let’s customize 403 error message adding this text:

<h1 color='red'>Error 403: The requested content is forbidden from public access.</h1>
<p>Try reloading the page and if it continue happening report the error emailing us at support@yoursite.com</p>

Creating a 500 custom error page

touch /usr/share/nginx/html/my_custom_500_error.html
nano -w /usr/share/nginx/html/my_custom_500_error.html

And the same goes for 500 errors, add this text to the file:

<h1 color='red'>Error 500: The requested content is forbidden from public access.</h1>
<p>Try reloading the page and if it continue happening report the error by emailing us at support@yoursite.com</p>

And that’s all you need. Of course this are very basic messages without any css style or graphic design, customizing the style and messages is up to you my friend.

How can I forward Nginx error pages to my custom pages?

Edit your nginx.conf file:

nano -w /etc/nginx/nginx.conf

Move into the server {} block configuration. If you already have error_page directive set, comment that configuration or remove as we are going to use the new one just created.

Add this lines:

        error_page 404 /custom_404.html;
        location = /custom_404.html {
            root /usr/share/nginx/html;
            internal;
        }

Do the same for all your custom pages, an example with the three custom error pages we created:

http {
...
...    
server {
...
        ...
error_page 404 /my_custom_404.html;
        location = /my_custom_404.html {
            root /usr/share/nginx/html;
            internal;
       }

error_page 403 /my_custom_404.html;
        location = /my_custom_404.html {
            root /usr/share/nginx/html;
            internal;
        }

error_page 500 /my_custom_500.html;
        location = /my_custom_404.html {
            root /usr/share/nginx/html;
            internal;
        }
...
...
}
}

On this examples we configured the custom error files paths, set the document root, and finally specified the files access as “internal” to ensure those are only accessible through internal Nginx redirects and not available for requests made by the clients.

Apply changes:

service nginx reload

How can I test this custom error pages?

Try loading some non existent URL like: http://yoursite.com/dontexist.html

Conclusion

As we’ve seen custom error pages are important in order to create human friendly messages for your users, and also to have a way to recieve alerts from them if your page is having critical errors. Creating custom error pages on Nginx now should be an easy task for you. Don’t forget that you can also add really cool graphic designs with a touch of humor.

Please let us know if you have any suggestions or comments to improve the article.

Popular search terms:

  • nginx if return custom error
  • usr/share/nginx/html/404 html
  • nginx custom error page
  • nginx 500 custom message
profile

Esteban Borges

Linux Geek, Webperf Addict, Nginx Fan. CTO @Infranetworking