NGINX Connection Refused: Complete Troubleshooting Guide

You've deployed your application behind NGINX, but when you try to access it, you're greeted with a "Connection Refused" error. This is one of the most frustrating issues in web server management because it can have multiple root causes. The error means that NGINX or your application backend isn't reachable at all—not a 4xx or 5xx HTTP error, but a complete network-level failure. Let's systematically diagnose and fix this issue.

Understanding "Connection Refused"

What This Error Means

"Connection Refused" is a TCP-level error that occurs when:

No service is listening on the requested port
The service is down or crashed
Network connectivity issues prevent reaching the service
Firewall rules are blocking the connection
Configuration errors prevent the service from starting

"Connection Refused" is different from HTTP errors like 404 or 500. It means the TCP connection itself cannot be established, indicating a more fundamental problem.

Common Scenarios

NGINX not running - The web server service is down
Application backend down - The upstream service isn't responding
Port misconfiguration - Services listening on wrong ports
Firewall blocking - Network rules preventing access
SELinux/AppArmor - Security policies blocking connections

Systematic Troubleshooting Approach

Step 1: Reproduce and Confirm the Error

First, confirm the exact error you're experiencing:

# Test from command line
curl -I http://localhost
curl -I http://your-domain.com

# Test with verbose output
curl -v http://localhost

Expected error output:

curl: (7) Failed to connect to localhost port 80: Connection refused

This confirms it's a TCP connection issue, not an HTTP error.

Step 2: Check NGINX Service Status

Verify if NGINX is running:

# Check service status
sudo systemctl status nginx

# Check if NGINX is running
ps aux | grep nginx

# Check NGINX processes
pgrep nginx

If NGINX is not running:

# Start NGINX
sudo systemctl start nginx

# Enable auto-start
sudo systemctl enable nginx

# Check for errors
sudo journalctl -u nginx -xe

Step 3: Verify NGINX is Listening on Correct Ports

Check if NGINX is actually listening on the expected ports:

# Check listening ports
sudo netstat -tulnp | grep nginx

# Alternative method
sudo ss -tuln | grep :80
sudo ss -tuln | grep :443

# Check all listening ports
sudo netstat -tulnp | grep LISTEN

Expected output:

tcp  0  0  0.0.0.0:80  0.0.0.0:*  LISTEN  1234/nginx: master
tcp  0  0  0.0.0.0:443 0.0.0.0:*  LISTEN  1234/nginx: master

If you see no output, NGINX is not listening on any ports, which means it's either not running or has configuration issues.

Step 4: Test NGINX Configuration

Check for configuration syntax errors:

# Test configuration syntax
sudo nginx -t

# Test with specific config file
sudo nginx -t -c /etc/nginx/nginx.conf

# Check configuration files
sudo nginx -T

Common configuration issues:

Missing semicolons
Incorrect file paths
Invalid syntax
Missing required directives

Step 5: Verify NGINX Configuration Files

Check your NGINX configuration:

# Check main configuration
sudo cat /etc/nginx/nginx.conf

# Check site configurations
sudo ls -la /etc/nginx/sites-enabled/
sudo cat /etc/nginx/sites-enabled/default

Example working configuration:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Step 6: Verify Application Backend

If NGINX is running but proxying to a backend, check if the application is running:

# Check if application is listening on expected port
sudo netstat -tulnp | grep :5000

# Test direct connection to application
curl http://localhost:5000

# Check application processes
ps aux | grep your-app-name

If application is not running:

# Start your application
sudo systemctl start your-app
# or
./start-your-app.sh

# Check application logs
sudo journalctl -u your-app -f

Step 7: Check Firewall and Network Rules

Verify that ports are not blocked by firewall:

# Check UFW status
sudo ufw status

# Check iptables rules
sudo iptables -L

# Check for specific port rules
sudo iptables -L | grep :80
sudo iptables -L | grep :443

Allow HTTP/HTTPS traffic:

# Allow HTTP
sudo ufw allow 80/tcp

# Allow HTTPS
sudo ufw allow 443/tcp

# Allow from specific IP
sudo ufw allow from 192.168.1.0/24 to any port 80

Step 8: Check Cloud Security Groups

If running on cloud platforms, verify security group rules:

AWS Security Groups:

Ensure port 80/443 is open
Check source IP restrictions
Verify instance is in correct subnet

GCP Firewall Rules:

Check VPC firewall rules
Verify target tags
Check source ranges

Step 9: Check SELinux and AppArmor

Verify security policies aren't blocking connections:

# Check SELinux status
sudo getenforce

# Check SELinux context
sudo ls -Z /usr/sbin/nginx

# Check AppArmor status
sudo aa-status

If SELinux is blocking:

# Temporarily disable for testing
sudo setenforce 0

# Check SELinux logs
sudo ausearch -m avc -ts recent

# Set proper context
sudo setsebool -P httpd_can_network_connect 1

Advanced Troubleshooting

Network Connectivity Testing

# Test local connectivity
telnet localhost 80

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

# Check routing
traceroute your-server-ip

# Test DNS resolution
nslookup your-domain.com

Process and Port Analysis

# Find what's using a specific port
sudo lsof -i :80
sudo lsof -i :443

# Check process tree
pstree -p

# Monitor network connections
sudo netstat -tulnp | grep LISTEN

Log Analysis

# Check NGINX error logs
sudo tail -f /var/log/nginx/error.log

# Check system logs
sudo journalctl -u nginx -f

# Check application logs
sudo tail -f /var/log/your-app/error.log

Common Root Causes and Solutions

Cause 1: NGINX Service Not Running

Symptoms: No processes, no listening ports Solution:

sudo systemctl start nginx
sudo systemctl enable nginx

Cause 2: Configuration Syntax Errors

Symptoms: NGINX fails to start, configuration test fails Solution:

sudo nginx -t
# Fix syntax errors in configuration files
sudo systemctl restart nginx

Cause 3: Port Already in Use

Symptoms: NGINX fails to start, port binding errors Solution:

# Find what's using the port
sudo lsof -i :80

# Kill the conflicting process
sudo kill -9 <PID>

# Or change NGINX to use different port

Cause 4: Application Backend Down

Symptoms: NGINX running but backend unreachable Solution:

# Check application status
sudo systemctl status your-app

# Restart application
sudo systemctl restart your-app

# Check application logs
sudo journalctl -u your-app -f

Cause 5: Firewall Blocking

Symptoms: External connections fail, local connections work Solution:

# Allow HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Check cloud security groups
# Update firewall rules

Cause 6: SELinux/AppArmor Restrictions

Symptoms: NGINX running but connections blocked Solution:

# Check security policy logs
sudo ausearch -m avc -ts recent

# Allow network connections
sudo setsebool -P httpd_can_network_connect 1

Prevention and Best Practices

1. Configuration Management

# Always test configuration before applying
sudo nginx -t

# Use version control for configurations
git add /etc/nginx/
git commit -m "Update NGINX configuration"

# Backup configurations
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup

2. Monitoring and Alerting

# Set up service monitoring
sudo systemctl enable nginx
sudo systemctl start nginx

# Monitor port availability
netstat -tulnp | grep :80

# Set up log monitoring
sudo tail -f /var/log/nginx/error.log

3. Health Checks

# Create health check script
cat > /usr/local/bin/nginx-health.sh << 'EOF'
#!/bin/bash
if ! systemctl is-active --quiet nginx; then
    echo "NGINX is not running"
    exit 1
fi

if ! netstat -tulnp | grep -q :80; then
    echo "NGINX not listening on port 80"
    exit 1
fi

echo "NGINX is healthy"
exit 0
EOF

chmod +x /usr/local/bin/nginx-health.sh

4. Automated Recovery

# Create auto-restart script
cat > /usr/local/bin/nginx-recovery.sh << 'EOF'
#!/bin/bash
if ! systemctl is-active --quiet nginx; then
    echo "$(date): NGINX is down, restarting..." >> /var/log/nginx-recovery.log
    sudo systemctl start nginx
fi
EOF

chmod +x /usr/local/bin/nginx-recovery.sh

# Add to crontab
echo "*/5 * * * * /usr/local/bin/nginx-recovery.sh" | sudo crontab -

Real-World Scenarios

Scenario 1: NGINX Configuration Error

Problem: NGINX fails to start due to syntax error Solution:

# Check configuration
sudo nginx -t

# Fix syntax error
sudo nano /etc/nginx/sites-enabled/default

# Restart NGINX
sudo systemctl restart nginx

Scenario 2: Application Backend Crash

Problem: NGINX running but application backend down Solution:

# Check application status
sudo systemctl status myapp

# Restart application
sudo systemctl restart myapp

# Verify backend is responding
curl http://localhost:5000

Scenario 3: Firewall Blocking

Problem: External connections fail, local connections work Solution:

# Check firewall status
sudo ufw status

# Allow HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Check cloud security groups

Conclusion

"Connection Refused" errors with NGINX can be frustrating, but with a systematic approach, you can quickly identify and resolve the issue:

Confirm the error - Use curl to reproduce the issue
Check NGINX status - Verify the service is running
Verify port binding - Ensure NGINX is listening on correct ports
Test configuration - Check for syntax errors
Verify backend - Ensure application is running
Check network rules - Verify firewall and security groups
Review security policies - Check SELinux/AppArmor

Remember:

Start with the basics - Service status and port binding
Test systematically - Don't skip steps
Check logs - They often contain the root cause
Verify network connectivity - Both local and external
Document your findings - For future reference

The key to resolving "Connection Refused" errors is systematic diagnosis. Start with service status, then move to configuration, network, and security policies.

Table of Contents