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.

%%OZI_ILB_PROTECT_10620c497c89eed07515bbbb2deb57bc%%

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

%%OZI_ILB_PROTECT_beb404a636b9a2b81c3963bc041f4561%%

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.

%%OZI_ILB_PROTECT_68d98b8654a800ce821426fa8bd45498%%

Ou:

%%OZI_ILB_PROTECT_2acf480480ac11b32b537d56825d6bc4%%

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:

%%OZI_ILB_PROTECT_40a51863e01017a4572219cec74a4944%%

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:

%%OZI_ILB_PROTECT_a6122933c81cd5c895df1cd13f5e2c91%%

Procure pelas diretivas:

%%OZI_ILB_PROTECT_3b178b9b7e7cc93725a927dbefae0cd7%%

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:

%%OZI_ILB_PROTECT_a68f3d872ae690cba56f5e7323787ce9%%

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

%%OZI_ILB_PROTECT_8e0beb782223e1470407b22d0d824d2f%%

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:

%%OZI_ILB_PROTECT_5318af186a736ea4c9b2e68013af6847%%

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:

%%OZI_ILB_PROTECT_2744ca29532b4e633bade1793fe62f69%%

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:

%%OZI_ILB_PROTECT_c7c0022a00d456dd0473e7f5089ca890%%

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:

%%OZI_ILB_PROTECT_15f60e674575847656d5beda47338790%%

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.