configure custom 404 page in nginx

How To Create Custom 404 Page in NGINX

Last updated on July 17th, 2024 at 05:09 am

By default, when NGINX cannot find a requested URL, it will respond with a 404: Page not found’ message. It is neither intuitive nor user-friendly and can cause site visitors to leave your website abruptly. To overcome this problem, it is advisable to create custom 404 page and show it instead of the default HTML one. So users will know what they need to do when they encounter 404 response.

NGINX allows you to configure custom 404 page for your website, which are automatically rendered in case a requested URL is not found on your website. This allows you to display intuitive next steps to your website visitors, when they are unable to find a page on your website. You can use these steps to configure custom error pages in NGINX, for various error codes such as 404, 403, 500, 502, etc. Here are the steps to create custom 404 page in NGINX.

Why Create Custom Error Pages

Typically, all web servers display plain HTML pages with terse messages in case of error responses such as 404, 405, 403, 500, etc. They are not user friendly and confuse the site visitors, leaving a bad user experience. Also, it reduces your search engine rankings.

It would have been super if web servers could automatically redirect to another web page on error response codes. Unfortunately, this cannot be done since redirect involves a separate request from browser, which doesn’t happen in case it receives an error response in the first place. That is why we need to setup a custom page for error responses. You can do this in NGINX using error_page directive.

What is Error_page directive

Error_page directive basically specifies the URI that will be displayed in case of specific errors. Here is its syntax.

error_page error_code(s) uri

Here is an example command to display error404.html URI for 404 error code.

error_page 404 /error404.html

When NGINX encounters the specific error (e.g. 404), it will do an internal redirection to URI specified in error_page directive matching the error code, say, 404. In this case, the request method is changed to GET irrespective of what user requested originally. You can also include variables in the above URI error404.html.

In the above case, the response code will still be 404. If you want to change it, you can do so with = operator. Here is an example to not only display error404.html page but also return 200 response code instead of 404.

error_page 404 =200 /error404.html

In fact, you can serve same page for more than one error code by simply mentioning them one after the other. Here is an example to serve same page for error codes 403, 404, and 405.

error_page 403 404 405 /error404.html

How To Create Custom 404 Page in NGINX

Now that we have a good understanding of error_page directive, here are the steps to create custom 404 page in NGINX.

1. Create 404 error page

Create custom error file error404.html using text editor like vi editor, or a page builder like Squarespace, WordPress, or Wix, and place it in website root folder /usr/nginx/share/html. You can change the file name as per your requirement.

$ sudo vi /usr/nginx/share/html/error404.html

Add the following code to it.

<h1 >Error 404</h1>
<p>Sorry, we're unable to find the requested page.</p>
<p>Please click <a href="/">here</a> to go to our home page instead</p>

In the above page, we display the error message saying the requested URL is not available. We also instruct the user to click on the link to home page. This is very important. Most websites do not tell what users need to when they encounter a 4xx or 5xx error response. That only confuses site visitors. It is important to provide a simple and clear CTA (call to action) on your custom page so that users do not leave your website cluelessly.

Also read : How to Limit Download Speed in NGINX

2. Open NGINX configuration file

Open terminal and run the following command to open NGINX server configuration file.

$ sudo vi /etc/nginx/nginx.conf

If you have configured separate virtual hosts for your website (e.g, such as /etc/nginx/sites-enabled/website.conf then open its configuration with the following command

$ sudo vi /etc/nginx/sites-enabled/website.conf

Alternatively, you can also open the default virtual host configuration file.

$ sudo vi /etc/nginx/sites-enabled/default

Also read : How to Enable GZIP compression in NGINX

3. Configure Custom 404 error page

We will add the error_page directive to configure custom error page for 404 response code. You can place it in httpserverlocation, or if server blocks. If you place it in http block, then the same page will be displayed for all websites running on your server. If you place it in server block, it will be displayed only for the website of that server block.

Add the following line to your server block

server {
error_page 404 /error404.html;
location = /error404.html {
root /usr/share/nginx/html;

In the above code, we specify error_page directive followed by error code followed by error404.html page to be served. We also mention the location path to error404.html with its root directory as /usr/share/nginx/html so that NGINX can properly find this file. This way NGINX will render error404.html page instead of returning 404:Page not found error response.

If you want to also serve the same page for other error codes such as 403 mention it after error_page directive before the filename to be served.

error_page 403 404 /error404.html;
location = /error404.html {
root /usr/share/nginx/html;

You can create similar web pages to serve other error codes. Here is an example to serve error5xx.html for error codes 500, 502, 503, 504.

error_page 500 502 503 504 /error5xx.html;
location = /error5xx.html {
root /usr/share/nginx/html;

Also read : How to Enable Caching in NGINX

4. Restart NGINX Server

Run the following command to check syntax of your updated config file.

$ sudo nginx -t

If there are no errors, run the following command to restart NGINX server.

$ sudo service nginx reload #debian/ubuntu
$ systemctl restart nginx #redhat/centos

That’s it. Now NGINX will automatically return your custom error page for 404 page not found errors. Similarly, you can configure custom error pages for other error codes such as 403, 500, 502, etc. by changing error code number and response URL in error_page directive.

Some Points to Remember

When you design a web page for 404 response code or any other error response, keep in mind the following points.

  1. Design the web page to be similar to other pages on your website. It means use the same logo, header, footer, theme and visual elements of other pages. This way the visitor is not put off and knows that they are still on the same site.
  2. Mention clear call to action or next steps the visitor needs to take to get out of this problem. This can be clicking a link, sending an email, or contacting site admin.


In this article, we have learnt how to serve a custom web page for 404 error response code. You can use the same steps to setup error pages for other response codes. It is important to setup such pages to avoid displaying default HTML pages that are not helpful. This not only improves user experience but also prevents search engines from penalizing your site unnecessarily.

Ubiq makes it easy to visualize data, and monitor them in real-time dashboards. Try Ubiq for free.