Skip to main content

Troubleshooting Common Nginx Issues

Now that you've mastered Nginx configuration, optimization, and deployment, it's time to tackle the inevitable: troubleshooting. In this lesson, you'll learn systematic approaches to diagnose and resolve common Nginx issues, from configuration errors to performance problems.

Learning Goals:

  • Develop a structured troubleshooting methodology
  • Identify and fix common configuration mistakes
  • Use Nginx logs effectively for debugging
  • Resolve connectivity and performance issues
  • Apply quick fixes for emergency situations

Systematic Troubleshooting Approach​

When facing Nginx issues, follow this structured approach:

  1. Check Nginx status - Is it running?
  2. Test configuration - Are there syntax errors?
  3. Examine logs - What do the error logs say?
  4. Verify connectivity - Can you reach the server?
  5. Test configuration changes - Does the issue persist?
Basic troubleshooting commands
# Check if Nginx is running
sudo systemctl status nginx

# Test configuration syntax
sudo nginx -t

# Check listening ports
sudo netstat -tulpn | grep nginx

# Follow error logs in real-time
sudo tail -f /var/log/nginx/error.log

Common Configuration Issues​

Syntax Errors and Validation​

Nginx is strict about configuration syntax. Always test before applying changes:

Testing configuration
sudo nginx -t
# Output: nginx: configuration file /etc/nginx/nginx.conf test failed
# This indicates syntax errors that need fixing
warning

Never reload Nginx without testing configuration first. A failed reload can take down your entire web service.

Server Block Conflicts​

Multiple server blocks listening on the same port can cause unexpected behavior:

/etc/nginx/sites-available/example.com
server {
    listen 80;
    server_name example.com;
    # This will be the default if no other server_name matches
}

server {
    listen 80 default_server;
    server_name _;
    # This is the explicit default server
}

Log Analysis Techniques​

Nginx logs are your best friend when troubleshooting. Learn to read them effectively.

Understanding Error Log Levels​

Setting appropriate log levels
error_log /var/log/nginx/error.log warn;
# Available levels: debug, info, notice, warn, error, crit, alert, emerg

Common Error Patterns​

Analyzing error logs
# Search for specific error types
grep -i "permission denied" /var/log/nginx/error.log
grep -i "connection refused" /var/log/nginx/error.log
grep -i "no such file" /var/log/nginx/error.log

# Count error occurrences by type
cat /var/log/nginx/error.log | cut -d' ' -f6- | sort | uniq -c | sort -nr

Permission and File Access Issues​

File permission problems are common, especially with static content and PHP processing.

Checking File Permissions​

Verifying file access
# Check if Nginx user can access files
sudo -u www-data ls -la /var/www/html/

# Test file readability
sudo -u www-data cat /var/www/html/index.html

# Fix common permission issues
sudo chown -R www-data:www-data /var/www/html/
sudo find /var/www/html/ -type f -exec chmod 644 {} \;
sudo find /var/www/html/ -type d -exec chmod 755 {} \;
tip

Use namei -l /path/to/file to check permissions at each directory level in the path.

Connectivity and Network Problems​

Port Binding Issues​

Diagnosing port conflicts
# Check what's using port 80/443
sudo lsof -i :80
sudo lsof -i :443

# Check if Nginx is listening
sudo ss -tulpn | grep nginx

# Test from another machine
telnet your-server-ip 80

Firewall and SELinux​

Firewall troubleshooting
# Check firewall status
sudo ufw status
sudo firewall-cmd --list-all

# Check SELinux (if enabled)
sudo getenforce
sudo ausearch -m avc -ts recent  # Check SELinux denials

Performance and Resource Issues​

Worker Process Problems​

Monitoring worker processes
# Check current connections
sudo nginx -s status  # If status module is enabled

# Monitor system resources
htop
sudo netstat -ant | wc -l  # Total connections

Memory and File Descriptor Limits​

Checking system limits
# Check open files limit
ulimit -n
cat /proc/$(cat /var/run/nginx.pid)/limits | grep "Max open files"

# Check memory usage
ps -o pid,user,%mem,command ax | grep nginx
Adjusting limits in nginx.conf
worker_rlimit_nofile 100000;
events {
    worker_connections 4096;
}

Quick Emergency Fixes​

When you need to restore service quickly:

Emergency procedures
# Stop Nginx immediately
sudo systemctl stop nginx

# Start with minimal config
sudo nginx -c /etc/nginx/nginx.conf.minimal

# Disable problematic site
sudo mv /etc/nginx/sites-enabled/broken-site /tmp/

# Emergency rate limiting
echo 'limit_req_zone $binary_remote_addr zone=emergency:10m rate=1r/s;' > /etc/nginx/conf.d/emergency.conf

Common Pitfalls​

  • Reloading without testing: Always run nginx -t before nginx -s reload
  • Incorrect file permissions: Nginx user (www-data/nginx) needs read access to static files and execute access to directories
  • Missing semicolons: Nginx configuration requires semicolons at the end of directives
  • Server block conflicts: Multiple default servers or overlapping server_name patterns
  • DNS issues: server_name not resolving or pointing to wrong IP
  • Upstream timeouts: Backend services not responding within configured timeouts
  • Buffer size issues: Request entities too large for configured buffers
  • SSL certificate problems: Expired, missing, or misconfigured certificates
  • IPv6 configuration: Listen directives missing IPv6 support when needed
  • Log file rotation: Log files filling up disk space

Summary​

Troubleshooting Nginx requires a systematic approach: verify the service is running, test configuration syntax, examine logs thoroughly, check permissions and connectivity, and monitor resource usage. Remember that most issues stem from configuration errors, permission problems, or resource constraints. Use the tools and techniques covered here to quickly identify and resolve common Nginx problems.

Nginx Troubleshooting and Diagnostics

What is the first command you should run when Nginx isn't working as expected?

Question 1/5