When you host your website on the NGINX web server, it will handle the client request, but when the request is not fulfilled, it will return an error.
This error will be displayed to a user via a basic HTML page with the error code (404, 403, 500, 503), as shown below.
NGINX 404 Error Page
Having a dynamic site with such an ugly-looking page will reduce the UI/UX impression of your site. However, NGINX provides you with an option to configure a custom error page for your site.
To do that, you need to create a custom HTML page and specify it in error_page directive of the NGINX configuration file, which will be used as the URI to serve the custom error page for the specified error in the configuration file.
Today, you will learn how to configure NGINX to handle single or multiple errors with custom HTML pages.
Prerequisites
- Nginx web server installed on your system
- Either you have root access or sudo privileges
- Custom template for error pages (source will be provided)
- Browser to test the result (Chrome, Firefox, etc)
Creating Your Custom 404 Error Page
First, we will learn to handle the 404 response code with a custom HTML page. For that, we will create a custom page that will be shown in place of the default NGINX response for status code 404 to the users.
For demo purposes, I’ve already created a sample HTML template page that displays the error message “Error 404, The requested page is not available, please contact to administrator.” when viewed.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Access denied</title>
<style>
* {
margin: 0;
padding: 0;
border: 0;
}
body {
padding: 10px;
}
.container {
margin-top: 10rem;
text-align: center;
}
.container .error {
font-size: 10rem;
}
.container .description {
font-size: 1.2rem;
}
@media screen and (max-width: 600px) {
.container .error {
font-size: 5rem;
}
}
</style>
</head>
<body>
<div class="container">
<div class="error">
Error 404
</div>
<div class="description">
THe requested page is not available, please contact to administrator.
</div>
</div>
</body>
</html>
You can copy the above HTML code and paste it into your text editor and save the file with the name “error-page.html“. Later on, you can change it to something different.
Now copy the “error-page.html” file into the NGINX document root directory located at the /var/www/html
path, using the below command.
$ sudo cp error-page.html /var/www/html/
The next part will be creating a config file (snippets) and configuring the nginx.conf file.
Configuring NGINX to Use Your Error Pages
First, we will create a new configuration file within the snippet directory located at the /etc/nginx/snippets
path with name error-page.conf
.
For that, create a snippets
directory. If it does not exist in the /etc/nginx
path, the below command will create a new directory with the name snippets
.
$ sudo mkdir -p /etc/nginx/snippets
Then execute the below command to create the error-page.conf
configuration file within the snippets
directory.
$ sudo nano /etc/nginx/snippets/error-page.conf
Once the file is open for editing, then copy and paste the below code into the configuration file and save it.
error_page 404 /error-page.html;
location = /error-page.html {
root /var/www/html;
internal;
}
From the above snippet code, whenever NGINX encounters a 404 response from the user end, it will return the error-page.html
as the response.
Next, we have to include error-page.conf
inside the NGINX configuration file. For that, execute the below command to open the NGINX configuration file.
$ sudo nano /etc/nginx/sites-enabled/default # For Ubuntu/Debian-based distro's
OR
$ sudo nano /etc/nginx/nginx.conf # For RHEL/Fedora-based distro's
Below is the output of the above command.
Opening NGINX configuration file
Copy the below line to include the absolute path of the snippet file and place it within the server
container in the NGINX configuration file.
include snippets/error-page.conf;
Below is the output after the changes.
NGINX configuration file after changes
Finally, you can restart the NGINX web server and test your page.
Restarting NGINX and Testing Your Page
Once all the required configuration changes are made, reload the NGINX web server using the following command.
$ sudo systemctl reload nginx
Finally, open your browser and visit any page that does not exist to view the error page, as shown below.
Custom 404 Response Page
Create Different Custom Pages for Each NGINX Error
NGINX allows you to easily set up multiple pages for different HTTP errors. Instead of creating a separate page and configuring each error page for the custom errors, we are providing you with a GitHub repository with premade custom error pages with a configuration that can be configured within seconds.
Execute the below commands step by step.
$ sudo mkdir -p /srv/http/default
$ sudo git clone https://github.com/denysvitali/nginx-error-pages /srv/http/default
$ mkdir -p /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
Also read: How To Change the Nginx Web Document Location in Linux
Now open the NGINX configuration file with your choice of text editor.
$ sudo nano /etc/nginx/sites-enabled/default # For Ubuntu/Debian-based distro's
OR
$ sudo nano /etc/nginx/nginx.conf # For RHEL/Fedora-based distro's
Add the below line inside the configuration file.
include snippets/error_pages.conf;
Last, reload your NGINX web server to apply the changes.
$ sudo systemctl reload nginx
Now you can simply visit any unknown page to check the error page, as shown below.
Custom error page
Also read: How to Change Nginx 80 Port in Linux
I hope this article might be useful for your journey to learning the NGINX web server. If you are still facing any issues, the comment section is open for you.
Innovative tech mind with 12 years of experience working as a computer programmer, web developer, and security researcher. Capable of working with a variety of technology and software solutions, and managing databases.