Nginx 502 Bad Gateway Deep Diagnosis Checklist

halfbrain_logo512adminJune 19, 2026
11 lượt xem

Nginx 502 Bad Gateway Deep Diagnosis Checklist

Nginx 502 Bad Gateway usually means Nginx could not get a valid response from the upstream service. For WordPress, the upstream is often PHP-FPM. For apps, it may be a Docker container, Node.js app or API service.

Core principle

502 is an upstream handoff failure. Nginx is reachable, but the backend is missing, crashed, unreachable or returning invalid data.

Checklist

  1. Confirm Nginx is responding.
  2. Identify the upstream for the affected URL.
  3. Check PHP-FPM or app service status.
  4. Check socket or TCP upstream target.
  5. Check whether the upstream is listening.
  6. Check Nginx error log for connect errors.
  7. Check backend logs.
  8. Check resource pressure on the server.
  9. Restart only the failed backend service if confirmed.
  10. Verify the URL and monitor logs after recovery.

Reusable lesson

This applies to PHP-FPM, Docker apps, reverse proxies, n8n, APIs, dashboards and custom workers behind Nginx.

Checklist Type Troubleshooting
Level Intermediate
Risk Level High Risk
Estimated Time 30–90 minutes

When to Use This Checklist

Use this checklist when Nginx returns 502 Bad Gateway for WordPress, PHP apps, Docker apps, APIs or reverse proxy services.

Required Tools

SSH access, Nginx error log, upstream config, PHP-FPM or app service, ss, systemctl, backend logs

Before You Start

Do not blame DNS or SSL first if Nginx is already returning 502. Focus on the upstream handoff.

Structured Checklist Steps

  1. Confirm Nginx response.
  2. Identify upstream.
  3. Check backend service.
  4. Check socket or TCP target.
  5. Check listener.
  6. Read Nginx error log.
  7. Read backend logs.
  8. Check resources.
  9. Restart confirmed failed backend.
  10. Verify recovery.
See also  WordPress Backup Checklist for VPS Websites

Verification Steps

  1. Upstream target is known.
  2. Backend service is active.
  3. Listener exists.
  4. Nginx error log no longer shows connect failure.
  5. URL returns expected response.

Rollback Plan

If backend restart does not fix 502, restore recent config changes and test the upstream directly before changing Nginx again.

Common Mistakes

  • Restarting Nginx instead of backend.
  • Wrong socket path.
  • Backend app crashed.
  • Docker container not running.
  • Ignoring server memory pressure.

Related Commands

curl -I https://example.com
sudo tail -n 100 /var/log/nginx/error.log
sudo systemctl status php8.2-fpm
ls -la /run/php/
sudo ss -tulpn
docker ps
free -h

Share:

Disclaimer: The guides, checklists, commands, and examples on HalfBrain.net are provided for educational and operational reference only. Server environments, hosting providers, software versions, security settings, and WordPress configurations can vary, so you should always review commands before running them on your own system. We do our best to keep the content accurate and useful, but we cannot guarantee that every command, configuration, or recommendation will fit every environment. Always back up your website, database, and server configuration before making changes. HalfBrain.net is not responsible for data loss, downtime, security incidents, misconfiguration, or other issues that may result from applying the information on this website. Use the material at your own discretion.

halfbrain_logo512
admin

HalfBrain.net is a practical field notebook for people who want to self-operate websites, VPS servers, Linux systems, Docker stacks, Nginx configurations, DNS records, SSL certificates, and AI automation workflows. Our goal is simple: turn messy infrastructure problems into clear, repeatable checklists, commands, and operating procedures. We focus on practical execution, not theory for theory’s sake.

Leave a Reply

Your email address will not be published. Required fields are marked *

Related articles: