---
title: "How to Debug 502 Bad Gateway errors"
url: "https://ploi.io/documentation/server/how-to-debug-502-bad-gateway-errors"
published: "2023-08-28"
last_updated: "2026-06-15"
---

# How to Debug 502 Bad Gateway errors

A 502 Bad Gateway error indicates that one server on the internet received an invalid response from another server. When you're working with a stack involving NGINX as a reverse proxy for a backend written in PHP or NodeJS, diagnosing and fixing a 502 error can involve several steps.

Here is a guide to help you debug 502 Bad Gateway errors for PHP or NodeJS apps running behind an NGINX reverse proxy on an Ubuntu system.

Preliminary Steps
-----------------

1\. **Check Error Logs**: Always start by checking the error logs.

\- NGINX: `/var/log/nginx/error.log`

\- PHP-FPM: `/var/log/php8.5-fpm.log` (File paths might differ based on PHP version)

\- NodeJS: check where you're outputting logs in your application.

2\. **Confirm Status**: Make sure your backend service (NodeJS or PHP-FPM for PHP apps) is running. You can do this with commands like `systemctl status php8.5-fpm` or `pm2 status` for NodeJS apps.

3\. **Test Local Access**: Try to access the app directly via [localhost](http://localhost) to bypass the NGINX proxy. This will help you understand if the problem lies with NGINX or your backend.

Debugging PHP (with PHP-FPM) and NGINX
--------------------------------------

### Common Issues and Solutions

#### 1. PHP-FPM Service is Down

**Error Sample in NGINX log**

```
2023/08/28 09:41:52 [error] 10151#10151: *1 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.0.1, server: localhost, request: "GET /index.php HTTP/1.1", upstream: "fastcgi://127.0.0.1:9000", host: "www.example.com"
```

**Solution**: Restart PHP-FPM service.

```
sudo systemctl restart php8.5-fpm
```

#### 2. Incorrect `fastcgi_pass` in NGINX Configuration

**Error Sample in NGINX log**

```
upstream sent too big header while reading response header from upstream
```

**Solution**: Open the NGINX configuration file for the site and ensure the `fastcgi_pass` directive points to the right location (usually `127.0.0.1:9000` or `/var/run/php/php8.5-fpm.sock`).

```
location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
}
```

#### 3. PHP-FPM Pool Configuration Error

**Error Sample in PHP-FPM log**

```
WARNING: [pool www] server reached max_children setting (5), consider raising it
```

**Solution**: Edit the PHP-FPM pool configuration usually found in `/etc/php/8.5/fpm/pool.d/www.conf`. Increase the value of `max_children`.

```
; In /etc/php/8.5/fpm/pool.d/www.conf
max_children = 20
```

Debugging NodeJS and NGINX
--------------------------

### Common Issues and Solutions

#### 1. NodeJS App Crashed

**Error Sample in NGINX log**

```
connect() failed (111: Connection refused) while connecting to upstream
```

**Solution**: Check the NodeJS app logs for any uncaught exceptions or other errors. Restart your app.

```
pm2 restart <your-app-name>
```

#### 2. Incorrect `proxy_pass` in NGINX Configuration

**Error Sample in NGINX log**

```
no resolver defined to resolve localhost
```

**Solution**: Ensure the `proxy_pass` is correct in the NGINX configuration file.

```
location / {
    proxy_pass http://localhost:3000;
}
```

#### 3. Port Mismatch

**Error Sample in NGINX log**

```
upstream prematurely closed connection while reading response header from upstream
```

**Solution**: Make sure that the port specified in `proxy_pass` matches the port on which your NodeJS app is running.

### Additional Tips

1\. **Check Firewall**: Ensure that the firewall is not blocking the ports used by NGINX or your backend.

2\. **Test Configuration**: Always test your NGINX configuration before applying changes with `nginx -t`.

By systematically going through these checks and solutions, you should be able to identify the cause of most 502 Bad Gateway errors related to PHP or NodeJS apps running behind an NGINX reverse proxy on Ubuntu.