Erro 502 Bad Gateway no Nginx: diagnóstico rápido e correções

O erro 502 Bad Gateway no Nginx é um dos problemas mais comuns em ambientes web que utilizam proxy reverso ou FastCGI. Esse erro indica, essencialmente, que o Nginx conseguiu receber a requisição do cliente, mas falhou ao tentar se comunicar com o serviço upstream responsável por processá-la, como PHP-FPM, aplicações Node.js ou outros backends.

Na prática, isso significa que o problema raramente está no Nginx em si, mas sim na comunicação com o serviço de aplicação. O diagnóstico correto exige analisar três pontos principais: disponibilidade do backend, configuração de comunicação (socket ou porta) e limites de recursos do servidor.

1. Verifique se o serviço upstream está ativo

O primeiro passo é garantir que o backend está rodando. Em ambientes com PHP, isso normalmente significa verificar o status do php-fpm. Se o serviço estiver parado ou travado, o Nginx não terá para onde encaminhar a requisição.

systemctl status php-fpm

Se o serviço não estiver ativo, reinicie:

systemctl restart php-fpm

Para aplicações Node.js ou outros serviços, verifique o processo correspondente (PM2, Docker, etc.).

2. Valide a configuração do proxy (socket ou porta)

Um dos erros mais comuns é a inconsistência entre o endereço configurado no Nginx e o backend real. No caso do PHP-FPM, essa comunicação pode ocorrer via socket Unix ou porta TCP, e qualquer divergência entre o que está configurado no Nginx e no PHP-FPM resultará diretamente em erro 502.

fastcgi_pass unix:/run/php/php8.1-fpm.sock;

Ou:

fastcgi_pass 127.0.0.1:9000;

No caso de uso de socket Unix, o caminho informado no fastcgi_pass precisa existir fisicamente no servidor. Esse arquivo é criado automaticamente pelo serviço do PHP-FPM quando ele está em execução.

Para verificar isso, acesse o servidor via SSH e execute:

ls -lah /run/php/

O resultado deve listar algo como php8.1-fpm.sock. Se o arquivo não existir, isso indica que o PHP-FPM não está rodando ou está configurado para usar outro caminho de socket.

Além disso, é fundamental verificar as permissões do socket. O usuário do Nginx (geralmente www-data) precisa ter permissão de leitura e escrita nesse arquivo. Caso contrário, mesmo com o socket existente, a comunicação falhará.

Essa configuração pode ser validada no arquivo de pool do PHP-FPM, normalmente localizado em:

/etc/php/8.1/fpm/pool.d/www.conf

Procure pelas diretivas:

listen = /run/php/php8.1-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Se estiver utilizando porta TCP, é necessário garantir que o PHP-FPM está escutando na mesma porta definida no Nginx. Verifique no mesmo arquivo de pool:

listen = 127.0.0.1:9000

Em seguida, valide se a porta está realmente aberta:

ss -ltnp | grep 9000

Se não houver nenhum processo escutando nessa porta, o PHP-FPM pode estar parado ou configurado incorretamente.

Garantir essa consistência entre Nginx e PHP-FPM é um dos passos mais importantes no diagnóstico do erro 502, pois qualquer divergência nessa camada impede completamente o processamento das requisições.

3. Analise os logs do Nginx e do backend

Os logs são fundamentais para entender a causa exata do erro. No Nginx, verifique o log de erro em tempo real:

tail -f /var/log/nginx/error.log

Mensagens como connect() failed (111: Connection refused) indicam que o backend não está aceitando conexões. Já erros como upstream timed out apontam para problemas de desempenho ou timeout.

Também é essencial verificar o log do PHP-FPM:

tail -f /var/log/php-fpm.log

4. Ajuste limites e timeouts

Em cenários de alta carga ou scripts demorados, o erro 502 pode ocorrer devido a timeout ou limitação de recursos. No Nginx, revise configurações como:

proxy_read_timeout 300;
fastcgi_read_timeout 300;

No PHP-FPM, verifique parâmetros como pm.max_children, pm.max_requests e request_terminate_timeout. Um pool mal dimensionado pode causar fila de requisições e indisponibilidade temporária.

5. Verifique uso de recursos do servidor

Consumo excessivo de CPU ou memória pode fazer o backend parar de responder. Use ferramentas como:

top
htop
free -m

Se o servidor estiver sob pressão, pode ser necessário otimizar a aplicação, aumentar recursos ou redistribuir carga.

6. Cenários comuns que causam 502

Algumas causas recorrentes incluem:

• PHP-FPM parado ou travado
• Socket inexistente ou com permissão incorreta
• Porta errada no fastcgi_pass ou proxy_pass
• Timeout insuficiente para scripts longos
• Excesso de conexões simultâneas
• Falta de memória no servidor

Identificar corretamente o cenário reduz drasticamente o tempo de resolução.

Se você estiver enfrentando esse tipo de problema em ambiente de produção ou precisa melhorar a estabilidade do seu servidor, contar com um ambiente bem configurado faz toda a diferença. Caso precise de apoio técnico ou análise mais aprofundada, é possível entrar em contato pelo formulário abaixo.