How to Create NGINX 500 Error Page

nginx 500 error page

When you run a website, your visitors are bound to get the occasional “500: Internal Server Error” response, in case your server returns an error. Similarly, they might also get different 500-level errors (502 – bad gateway, 503 – service unavailable) due to server problems. In such cases, it’s advisable to serve intuitive error pages instead of the default server response. Here’s how to create NGINX 500 Error pages that can be returned in case of server-related errors.


How to Create NGINX 500 Error Page

Here are the steps to create NGINX 500 Error page. Before you proceed, please ensure that you have installed NGINX on your system.


1. Create Custom Error Page

First, you need to create a custom error page that can be returned in case of server errors (500, 502, 503, etc), and place this at /usr/share/nginx/html

$ sudo vim /usr/share/nginx/html/custom_50x.html


Add the following lines to it, save and close the file

<h1>Oops! Something went wrong...</h1>
<p>We seem to be having some technical difficulties. Hang tight.</p>


2. Configure NGINX to use Error Page

Open the server block file at /etc/nginx/sites-enabled that you want to configure. If you use a different file, you can use that one. In our example, we use the default server block titled “default”

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


3. Redirect 50x Errors to Custom Page

We use error_page directive to point NGINX to the location of our custom error page, so it can be served in case of 50x (502, 503, etc) errors.

We will put it in a location block so that its root matches the file system, and it is accessible only via internal errors and not external requests.

We will also create a dummy URL (/testing) that throws a 50x error. In this case, it will give a “502: Bad Gateway” error. Open Nginx config file in a text editor

$ vi /etc/nginx/nginx.conf


and add the following lines


server {
listen 80 default_server;
listen [::]:80 default_server ipv6only=on;

. . .

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

 location /testing {
   fastcgi_pass unix:/does/not/exist;


4. Test Nginx Configuration

Test your NGINX configuration with the following command

$ sudo nginx -t


Restart NGINX to apply changes

$ sudo service nginx restart


Now open your browser and go to our test page (e.g http://your_server_ip_or_domain/testing) that is expected to throw a server error. You will see the custom page that you had created to handle server errors.

nginx 500 error page



About Sreeram Sreenivasan

Sreeram Sreenivasan is the Founder of Ubiq, a business dashboard & reporting platform for small & medium businesses. Ubiq makes it easy to build business dashboards & reports for your business. Try it for free today!