---
service: nginx
symptoms: 502 Bad Gateway, 504 Gateway Timeout, upstream connection refused, nginx not starting, failed to bind socket, permission denied reading config, configuration test failed
tags: nginx, web, http, https, proxy, upstream, reverse-proxy, load-balancer
---

## Symptoms

- `502 Bad Gateway` — nginx reached the upstream but got an invalid response, or upstream is down
- `504 Gateway Timeout` — upstream took too long to respond
- `111: Connection refused` in nginx error log — upstream process is not running or not on the expected port
- `nginx.service: Start request repeated too quickly` — crash-loop; check error log
- `[emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)` — port conflict
- `[emerg] open() ... failed (13: Permission denied)` — file permission issue

## Diagnostics

### Service status

```
systemctl status nginx
```

### Config test

```
nginx -t
```

A config error is the most common reason for nginx failing to start or reload.

### Error log

```
journalctl -u nginx -n 100
tail -n 100 /var/log/nginx/error.log
```

For 502/504 errors look for: `connect() failed`, `upstream timed out`, `no live upstreams`.

### Access log — recent requests

```
tail -n 50 /var/log/nginx/access.log
```

### Check upstream services

For `proxy_pass` targets, verify the upstream is running:
```
systemctl status <upstream-service>
ss -tlnp | grep <upstream-port>
```

Common upstreams: `gunicorn`, `uwsgi`, `node`, `puma`, `php-fpm`.

### Port binding conflicts

```
ss -tlnp | grep ':80\|:443'
```

### Config files

```
cat /etc/nginx/nginx.conf
ls /etc/nginx/sites-enabled/
cat /etc/nginx/sites-enabled/<vhost>
```

Check `proxy_pass`, `upstream` blocks, `proxy_connect_timeout`, `proxy_read_timeout`.

## Remediation

**Upstream service not running:**
Start the upstream service, then verify nginx resumes proxying.

**Config syntax error:**
Fix the error shown by `nginx -t`, then:
```
systemctl reload nginx
```

**Port already in use:**
Find the conflicting process with `ss -tlnp | grep :80`, stop it, then restart nginx.

**Upstream timeouts — increase timeouts (caution: treat the slow upstream as the root cause):**
```nginx
proxy_connect_timeout 10s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
```

**Permission denied on log or socket file:**
```
ls -la /var/log/nginx/
ls -la /run/nginx.pid
chown -R www-data:www-data /var/log/nginx/
```