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.

Aaron Kili
Aaron Kili is a Linux and F.O.S.S enthusiast, an upcoming Linux SysAdmin, web developer, and currently a content creator for TecMint who loves working with computers and strongly believes in sharing knowledge.

Each tutorial at TecMint is created by a team of experienced Linux system administrators so that it meets our high-quality standards.

Join the TecMint Weekly Newsletter (More Than 156,129 Linux Enthusiasts Have Subscribed)
Was this article helpful? Please add a comment or buy me a coffee to show your appreciation.

7 thoughts on “How to Create Custom 404 Error Page in NGINX”

    • @Demetry,

      Instead creating custum error configuration file, I suggest you to add following lines within the http block to set up the custom error page in the mail /etc/nginx/nginx.conf configuration file.

      http {
          # ... Other configuration settings ...
      
          server {
              listen 80;
              server_name your_domain.com;  # Replace with your actual domain name
      
              # Location block for the custom error page
              location / {
                  error_page 404 403 500 503 /error-page.html;
                  root /var/www/html;  # Replace with the actual path to your HTML file
                  index index.html;
              }
      
              # ... Other server settings ...
          }
      }
      

      After making the changes, restart NGINX to apply the changes:

      $ sudo systemctl restart nginx
      
      Reply
  1. On Runcloud I get these options under Type window.

    Should I go with ‘location.main-before’?

    I want to set a 404 error page for a static custom website.

    Thanks.

    Reply
  2. Hi, great article thanks!

    My client sends an HTTP header – X-Correlation-Id – and when nginx there is a circumstance when nginx sends a 404, I’d like to include in the 404 page, the X-Correlation-Id HTTP Header, with the same value, so that we can match up nicely.

    How do I do that? Thank you!

    Reply
  3. Hello, I followed your guide, and implemented the directions but is not getting to work.

    nginx: [emerg] “internal” directive is not allowed here in /etc/nginx/snippets/custom-error-page.conf:4.

    I have tried placing include /etc/nginx/snippets/custom-error-page.conf; at different places in the nginx.conf file and get a different error message.

    Thanks

    Reply
  4. Hello!

    When I place the include snippets/custom-error-page.conf; inside the http context, I get the error —

    nginx: [emerg] "location" directive is not allowed here in /etc/nginx/snippets/custom-error-page.conf:

    Reply
    • @Umata

      There is already an include directive to include all files under snippets/ somewhere in your NGINX configuration structure, try to check your main config file or other config files.

      Reply

Leave a Reply to Umata Cancel reply

Thank you for taking the time to share your thoughts with us. We appreciate your decision to leave a comment and value your contribution to the discussion. It's important to note that we moderate all comments in accordance with our comment policy to ensure a respectful and constructive conversation.

Rest assured that your email address will remain private and will not be published or shared with anyone. We prioritize the privacy and security of our users.