NGINX: Create Custom 404 / 403 Error Pages on Linux or Unix

How do I create a custom static HTTP 404 or HTTP 403 error page under nginx web server running on Linux or Unix-like system?

Nginx is a free and open source web server. It also act as a reverse proxy, caching and load balancer server. This tutorial shows, how to configure Nginx to use custom error pages for 404/403 on Linux or Unix-like system.

How to configure Nginx to use custom 404 error page

First create a 404.html in your document root. The default is location is /usr/local/nginx/html/ or /var/www/htm/. So create a HTML file as follows:
# vi /usr/local/nginx/html/404.html
OR
# vi /var/www/html/404.html
Sample outputs:

<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>Error 404 Not Found</title>
<style>
<!--
	body {font-family: arial,sans-serif}
	img { border:none; }
//-->
</style>
</head>
<body>
<blockquote>
	<h2>Error 404 Not Found</h2>
	<p>Our apologies for the temporary inconvenience. The requested URL was not found on this server.  We suggest you try one of the links below:
	<ul>
		  <li><b>Verify url and typos</b> - The web page you were attempting to view may not exist or may have moved - try <em>checking the web address for typos</em>.<//li>
		  <li><b>E-mail us</b> - If you followed a link from somewhere, please let us know at <a href="mailto:[email protected]">[email protected]</a>. Tell us where you came from and what you were looking for, and we'll do our best to fix it.</li>
	</ul>
</blockquote>
</body>
</html>

How to configuring Nginx to use my 404.html file as error page

Edit /usr/local/nginx/conf/nginx.conf file, enter:
# vi /usr/local/nginx/conf/nginx.conf
OR
# vi /etc/nginx/sites-available/default
Append / edit config as follows:

error_page   404  =  /404.html;

An example to prevent clients fetching error pages directly:

error_page 404 /404.html;
location  /404.html {
  internal;
}

An example of HTTP 403 error page:

       error_page 403 /403.html;
       location = /403.html {
           root   html;
           allow all;
           internal;
       }

The error_page can be placed in only http, server and location directives. Save and close the file. Reload the nginx server, enter:
# /usr/local/nginx/sbin/nginx -t && /usr/local/nginx/sbin/nginx -s reload
OR
# nginx -t && nginx -s reload
OR
$ sudo systemctl reload nginx
Here is a sample error page from my site when visited (your-domain/404dfoo):

Fig.01: Sample custom error 404 page in Nginx

How do I redirect to a specific URL for error processing?

Yes, URL redirects for error processing is possible as follows:

#
# Redirect to forbidden.php for HTTP status code 403
#
error_page 403      https://sxi.io/error/forbidden.php;
 
#
# Redirect to notfound.pl for HTTP status code 404 
# with redirect status codes to 301
#
error_page 404 =301 https://sxi.io/cgi-bin/notfound.pl;

A list of common error code

  1. HTTP 404 – Web page not found on this server.
  2. HTTP 403 – The server is configured to deny access to your request. Usually login urls such as /wp-admin/ or /phpmysqladmin/ are blocked using this method.
  3. HTTP 500/502/503/504 – Internal server problem such as miss configured server or back-end down.

For more info see Nginx documentation.

Posted by: SXI ADMIN

The author is the creator of SXI LLC and a seasoned sysadmin, DevOps engineer, and a trainer for the Linux operating system/Unix shell scripting. Get the latest tutorials on SysAdmin, Linux/Unix and open source topics via RSS/XML feed or weekly email newsletter.