Nginx is a powerful and flexible web server that underpins millions of websites worldwide. Known for its high performance, low resource consumption, and impressive scalability, Nginx is an ideal choice for projects of any size, from small personal sites to large-scale applications. However, like any software, Nginx can sometimes present issues and errors that may disrupt smooth operation. In this article, we’ll examine some common errors users encounter with Nginx and offer troubleshooting tips to resolve them effectively.

After reading this guide, you’ll be equipped to manage your Nginx web server more efficiently and troubleshoot any issues that may arise with confidence.

Table of Contents

1. Requirements
2. System Update
3. Installing Nginx
4. Common Nginx Errors and Solutions

• Address family not supported by protocol
• Default Nginx Page
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error
• 502 Bad Gateway
• 504 Gateway Timeout

Requirements

Before diving into troubleshooting with Nginx, ensure that your system meets the following prerequisites:

• Linux Distribution: Ubuntu 20.04, CentOS, AlmaLinux, Debian, or another compatible version
• User Privileges: Root or a user with sudo privileges
• Nginx Version: The latest stable version of Nginx installed

System Update

Keeping your system up to date is essential to prevent security vulnerabilities and to reduce errors. Before installing or configuring any software, ensure your system is updated with the following command:

sudo apt update -y && sudo apt upgrade -y

This command updates all packages on your system to their latest versions.

Installing Nginx

If Nginx isn’t already installed, you can do so with the following command:

sudo apt install nginx -y

After installing Nginx, start the service and enable it to run on system startup:

sudo systemctl start nginx
sudo systemctl enable nginx

To check if Nginx is running correctly, use:

sudo systemctl status nginx

If the output shows “active (running)”, then Nginx is running successfully.

Common Nginx Errors and Solutions

Below are some frequent errors users encounter with Nginx and step-by-step solutions to address them.

1. Address family not supported by protocol

This error typically occurs when Nginx is newly installed on a system without IPv6 support. You may see an error message like this:

nginx: [emerg] socket() [::]:80 failed (97: Address family not supported by protocol)
nginx: configuration file /etc/nginx/nginx.conf test failed

This error indicates that Nginx is attempting to listen on IPv6 but the system doesn’t support it. Follow these steps to fix it:

1. Open the Nginx configuration file:

   sudo nano /etc/nginx/sites-available/default

2. Locate the line containing listen [::]:80 default_server; and comment it out by adding a # at the beginning:

   # listen [::]:80 default_server;

3. Save the file, exit, and restart Nginx:

   sudo systemctl restart nginx

Nginx will now run using IPv4 only.

2. Default Nginx Page

After a new Nginx installation, accessing your server’s IP address or domain may display the default Nginx page. While not an error, it indicates that Nginx is serving its default page rather than your content. Here’s how to set up your configuration to display your site’s content instead:

1. Open the default configuration file:

   sudo nano /etc/nginx/sites-available/default

2. Set up root and index directives to match your website files:

   server {
       listen 80;
       server_name example.com;
       root /var/www/html;
       index index.html index.htm;
   }

3. Save and exit the file. Link this configuration to the sites-enabled directory:

   sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/

4. Verify the configuration and reload Nginx:

   sudo nginx -t
   sudo systemctl reload nginx

3. 403 Forbidden

A 403 Forbidden error occurs when you don’t have permission to access a resource. This often results from incorrect directory or file permissions. Here’s how to troubleshoot:

1. Check the permissions of your web directory. Ensure they are set to 755:

   sudo chmod -R 755 /var/www/html

2. If permissions are correct, check the Nginx configuration for access restrictions, such as an IP restriction:

   sudo nano /etc/nginx/sites-available/default

3. After making adjustments, restart Nginx:

   sudo systemctl restart nginx

4. 404 Not Found

This error indicates that the server couldn’t find the requested file. This commonly results from an incorrect root or index directive in the configuration. To resolve this:

1. Confirm the root directory is set correctly:

   sudo nano /etc/nginx/sites-available/default

Ensure it points to the correct location, like /var/www/html.

2. Save and close the file, then restart Nginx:

   sudo systemctl restart nginx

5. 500 Internal Server Error

A 500 Internal Server Error typically indicates a server issue. Here’s how to diagnose it:

1. Check Nginx’s error log for specific error messages:

   sudo tail -f /var/log/nginx/error.log

2. If your application uses PHP, check the status of PHP-FPM:

   sudo systemctl status php7.4-fpm

3. If PHP-FPM is inactive, restart it:

   sudo systemctl restart php7.4-fpm

4. Test the Nginx configuration:

   sudo nginx -t

6. 502 Bad Gateway

This error indicates that Nginx couldn’t reach the backend server. To troubleshoot:

1. Verify that PHP-FPM or another backend service is running:

   sudo systemctl status php7.4-fpm

2. If the service is down, restart it:

   sudo systemctl restart php7.4-fpm

3. Confirm the backend server configuration in Nginx.

7. 504 Gateway Timeout

A 504 Gateway Timeout error occurs when Nginx times out waiting for a response from the backend server. Here’s how to increase the timeout settings:

1. Verify that the backend server (PHP, Node.js, etc.) is functioning.
2. Increase the timeout values in the Nginx configuration file:

   sudo nano /etc/nginx/nginx.conf

Add or adjust the following settings:

   proxy_connect_timeout 600;
   proxy_send_timeout 600;
   proxy_read_timeout 600;

3. Restart Nginx:

   sudo systemctl restart nginx

Conclusion

Nginx is a robust and adaptable web server, but encountering errors is sometimes inevitable. This guide covers some of the most common Nginx issues and offers practical solutions to ensure your server runs smoothly. With this knowledge, you’ll be prepared to troubleshoot and resolve Nginx errors efficiently, keeping your web server and applications in top shape.