How to Create Custom 404 Error Page in NGINX

Every time NGINX encounters an error as it attempts to process a client’s request, it returns an error. Each error includes an HTTP response code and a short description. The error usually is displayed to a user via a simple default HTML page.

Fortunately, you can configure NGINX to display custom error pages to your site’s or web application’s users. This can be achieved using the NGINX’s error_page directive which is used to define the URI that will be shown for a specified error. You can also, optionally use it to modify the HTTP status code in the response headers sent to a client.

In this guide, we will show how to configure NGINX to use custom error pages.

Create a Single Custom Page for All NGINX Errors

You can configure NGINX to use a single custom error page for all errors that it returns to a client. Start by creating your error page. Here is an example, a simple HTML page that displays the message:

“Sorry, the page can't be loaded! Contact the site's administrator or support for assistance.” to a client.

Sample HTML Nginx Custom page code.

<!DOCTYPE html>
<html>
<head>

<style type=text/css>

* {
	-webkit-box-sizing: border-box;
	box-sizing: border-box;
}

body {
	padding: 0;
	margin: 0;
}

#notfound {
	position: relative;
	height: 100vh;
}

#notfound .notfound {
	position: absolute;
	left: 50%;
	top: 50%;
	-webkit-transform: translate(-50%, -50%);
	-ms-transform: translate(-50%, -50%);
	transform: translate(-50%, -50%);
}

.notfound {
	max-width: 520px;
	width: 100%;
	line-height: 1.4;
	text-align: center;
}

.notfound .notfound-error {
	position: relative;
	height: 200px;
	margin: 0px auto 20px;
	z-index: -1;
}

.notfound .notfound-error h1 {
	font-family: 'Montserrat', sans-serif;
	font-size: 200px;
	font-weight: 300;
	margin: 0px;
	color: #211b19;
	position: absolute;
	left: 50%;
	top: 50%;
		-webkit-transform: translate(-50%, -50%);
		-ms-transform: translate(-50%, -50%);
		transform: translate(-50%, -50%);
}

@media only screen and (max-width: 767px) {
	.notfound .notfound-error h1 {
		font-size: 148px;
	}
}

@media only screen and (max-width: 480px) {
	.notfound .notfound-error {
	height: 148px;
	margin: 0px auto 10px;
}
.notfound .notfound-error h1 {
	font-size: 120px;
	font-weight: 200px;
}
.notfound .notfound-error h2 {
	font-size: 30px;
}
.notfound a {
	padding: 7px 15px;
	font-size: 24px;
}
.h2 {
	font-size: 148px;
}
}
</style>
</head>
<body>
<div id="notfound">
	<div class="notfound">
		<h1>Sorry the page can't be loaded!</a></h1>
		<div class="notfound-error">
			<p>Contact the site's administrator or support for assistance.</p>
		</div>
	</div>
</div>
</body>
</html>

 

Save the file with an appropriate name for example error-page.html and close it.

Next, move the file to your document root directory (/var/www/html/). If the directory doesn’t exist, you can create it using the mkdir command, as shown:

$ sudo mkdir -p  /var/www/html/
$ sudo cp error-page.html /var/www/html/

Then configure NGINX to use the custom error page using the error_page directive. Create a configuration file called custom-error-page.conf under /etc/nginx/snippets/ as shown.

$ sudo mkdir /etc/nginx/snippets/
$ sudo vim /etc/nginx/snippets/custom-error-page.conf 

Add the following lines to it:

error_page 404 403 500 503 /error-page.html;
location = /error-page.html {
        root /var/www/html;
        internal;
}

This configuration causes an internal redirect to the URI/error-page.html every time NGINX encounters any of the specified HTTP errors 404, 403, 500, and 503. The location context tells NGINX where to find your error page.

Save the file and close it.

Now include the file in the http context so that all server blocks use the error page, in the /etc/nginx/nginx.conf file:

$ sudo vim /etc/nginx/nginx.conf

The include directory tells NGINX to include the configuration in the specified .conf file:

include snippets/custom-error-page.conf;

Alternatively, you can include the file for a specific server block (commonly known as vhost), for example, /etc/nginx/conf.d/mywebsite.conf. Add the above include directive in the server {} context.

Save your NGINX configuration file and reload the service as follows:

$ sudo systemctl reload nginx.service

And test from a browser if the setup is working fine.

Nginx Custom 404 Page
Nginx Custom 404 Page

Create Different Custom Pages for Each NGINX Error

You can also set up different custom error pages for each HTTP error in NGINX. We discovered a good collection of custom nginx error pages created by Denys Vitali on Github.

To set up the repository on your server, run the following commands:

$ sudo git clone https://github.com/denysvitali/nginx-error-pages /srv/http/default 
$ sudo mkdir /etc/nginx/snippets/
$ sudo ln -s /srv/http/default/snippets/error_pages.conf /etc/nginx/snippets/error_pages.conf
$ sudo ln -s /srv/http/default/snippets/error_pages_content.conf /etc/nginx/snippets/error_pages_content.conf

Next, add the following configuration in either your http context or each server block/vhost:

include snippets/error_pages.conf;

Save your NGINX configuration file and reload the service as follows:

$ sudo systemctl reload nginx.service

Also, test from a browser if the configuration is working as intended. In this example, we tested the 404 error page.

Nginx Custom 404 Error Page
Nginx Custom 404 Error Page

That’s all we had for you in this guide. NGINX’s error_page directive allows you to redirect users to a defined page or resource or URL when an error occurs. It also optionally allows for modification of the HTTP status code in the response to a client. For more information, read the nginx error page documentation.

If You Appreciate What We Do Here On TecMint, You Should Consider:

TecMint is the fastest growing and most trusted community site for any kind of Linux Articles, Guides and Books on the web. Millions of people visit TecMint! to search or browse the thousands of published articles available FREELY to all.

If you like what you are reading, please consider buying us a coffee ( or 2 ) as a token of appreciation.

Support Us

We are thankful for your never ending support.

Leave a Reply

Your email address will not be published.