Corrigindo Erros 502 Bad Gateway no Nginx: Guia Passo a Passo

Corrigir erros 502 Bad Gateway no Nginx começa com o entendimento de que o Nginx geralmente é o mensageiro, não a fonte original da falha. Um 502 significa que o Nginx tentou se comunicar com um serviço upstream e não obteve uma resposta válida.

Esse serviço upstream pode ser um aplicativo Node.js, PHP-FPM, Gunicorn, Puma, um contêiner ou outro servidor HTTP. Seu trabalho é encontrar onde a transferência falha.

O que um 502 Bad Gateway Significa no Nginx

O Nginx comumente fica na frente de um servidor de aplicação. Ele aceita tráfego público, lida com TLS, serve arquivos estáticos e encaminha requisições dinâmicas para o upstream.

Um 502 aparece quando essa conexão upstream falha ou retorna algo que o Nginx não pode usar. Causas comuns incluem:

• O processo da aplicação está parado.
• O Nginx aponta para a porta ou socket errada.
• Um socket Unix tem as permissões erradas.
• O serviço upstream trava durante a requisição.
• Um firewall ou rede de contêineres bloqueia a conexão.
• O upstream envia uma resposta HTTP inválida.

Comece pelo caminho exato da requisição que falha. Se apenas /api retorna 502, mas as páginas estáticas carregam, seu serviço de arquivos estáticos está ok e o proxy ou backend da aplicação é provavelmente o problema. Se todas as páginas falham, o problema pode ser mais amplo, como Nginx, DNS ou disponibilidade do upstream.

Passo 1: Verifique o Status e a Configuração do Nginx

Primeiro, confirme que o Nginx está rodando:

systemctl status nginx

Depois, teste a configuração:

nginx -t

Se o teste de configuração falhar, corrija isso antes de perseguir a aplicação. O Nginx pode ainda estar rodando com uma configuração antiga, ou pode falhar ao recarregar.

Após um teste de configuração bem-sucedido, recarregue o Nginx:

systemctl reload nginx

Não reinicie cegamente em um servidor ocupado a menos que você entenda o impacto. Recarregar geralmente é suficiente após uma mudança de configuração e é menos disruptivo.

Em seguida, inspecione o bloco de servidor ativo. Procure por proxy_pass, fastcgi_pass ou uwsgi_pass. Um proxy reverso típico pode incluir:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Isso significa que o Nginx espera uma aplicação na porta local 3000. Se a aplicação realmente escuta na 3001, ou apenas dentro de uma rede Docker, o Nginx falhará.

Para verificações mais focadas em comandos, veja Comandos de teste de configuração do Nginx.

Passo 2: Verifique o Serviço Upstream

Agora teste o upstream diretamente do host do Nginx. Se o Nginx faz proxy para 127.0.0.1:3000, execute:

curl -i http://127.0.0.1:3000/

Se isso falhar, o problema não é o navegador ou o DNS público. O Nginx não consegue alcançar o backend porque o backend está inativo, ouvindo em outro lugar ou rejeitando a requisição.

Verifique o processo da aplicação:

ss -ltnp

Procure pela porta esperada. Se o serviço usa um socket Unix, verifique o caminho do socket:

ls -l /run/app/app.sock

O usuário do worker do Nginx deve ser capaz de acessar esse socket. Em muitos sistemas Linux, o Nginx roda como www-data, nginx ou um usuário específico do serviço. Se o socket pertence a um usuário diferente e não é legível ou gravável pelo grupo conforme necessário, o Nginx pode registrar um erro de permissão e retornar 502.

Para uma configuração PHP-FPM, confirme que o pool está rodando:

systemctl status php-fpm

O nome do serviço pode incluir uma versão, como php8.2-fpm, dependendo da distribuição.

Passo 3: Leia o Log de Erros do Nginx

O log de erros do Nginx geralmente informa qual modo de falha você está enfrentando. Mensagens de log comuns incluem:

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

Isso significa que o Nginx alcançou o host, mas nada aceitou a conexão naquela porta.

upstream timed out while reading response header from upstream

Isso significa que o Nginx conectou, mas o backend não respondeu a tempo.

permission denied while connecting to upstream

Isso geralmente aponta para permissões de socket Unix ou controles de segurança como SELinux.

Verifique erros recentes com:

tail -n 100 /var/log/nginx/error.log

Em sistemas baseados em systemd, você também pode verificar:

journalctl -u nginx -n 100

Combine o timestamp no log com o horário da sua requisição no navegador. Isso evita que você persiga erros antigos que não são mais relevantes.

Para um fluxo de trabalho de log mais aprofundado, veja analisando logs de erro do Nginx.

Passo 4: Corrija as Causas Raiz Mais Comuns

Depois de saber o modo de falha, aplique a menor correção que corresponda a ele.

Se a aplicação não está rodando, inicie ou reinicie o serviço da aplicação:

systemctl restart your-app

Depois, teste o upstream com curl antes de testar através do Nginx.

Se o Nginx aponta para a porta errada, atualize o alvo proxy_pass e recarregue o Nginx. Certifique-se também de que sua aplicação e o Nginx concordam sobre IPv4 versus IPv6. Uma aplicação ouvindo em 127.0.0.1 não é o mesmo que uma ouvindo apenas em ::1.

Se o Docker estiver envolvido, verifique se o Nginx roda no host ou dentro de um contêiner. 127.0.0.1 dentro de um contêiner aponta para aquele contêiner, não para o host. Você pode precisar de um nome de serviço Docker, rede bridge ou porta publicada.

Se o upstream expirar, verifique os logs da aplicação. O backend pode estar travado em consultas de banco de dados, chamadas de API externas ou trabalho de inicialização. Aumentar os timeouts do Nginx pode esconder sintomas, mas não corrigirá uma aplicação quebrada ou sobrecarregada.

Quando Chamar um Profissional

Traga um engenheiro sênior ou provedor de hospedagem quando erros 502 afetarem a produção e a causa não for óbvia após verificar logs, status do upstream e implantações recentes. Também peça ajuda se o problema envolver balanceadores de carga, orquestração de contêineres, política SELinux ou ajuste de timeout em alto tráfego.

Para sistemas de produção, evite reinicializações aleatórias repetidas. Elas podem limpar evidências e tornar a interrupção mais difícil de entender.

Um erro 502 Bad Gateway é corrigível quando você rastreia o caminho da requisição em ordem. Confirme que o Nginx é válido, teste o upstream diretamente, leia a linha exata do log de erro e aplique a correção que corresponde à falha. Essa abordagem é mais rápida e segura do que alterar timeouts ou reiniciar serviços cegamente.