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.2-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.2-fpm or pm2 status for NodeJS apps.

3. Test Local Access: Try to access the app directly via 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.2-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.2-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.2/fpm/pool.d/www.conf. Increase the value of max_children.

; In /etc/php/8.2/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.