Como corrigir o erro 502 Bad Gateway no Nginx (passo a passo)

Um erro 502 Bad Gateway no Nginx geralmente significa que o Nginx não conseguiu receber uma resposta válida de um servidor upstream, como o PHP-FPM, o Node.js ou outra aplicação de backend.

As causas mais comuns são serviços de aplicação parados, portas ou sockets upstream incorretos e processos de backend que falham ou encerram conexões inesperadamente.

Comece verificando os logs de erro do Nginx. Eles geralmente revelam exatamente por que a conexão falhou.

Este guia apresenta sete etapas práticas para diagnosticar problemas em servidores Linux que executam o Nginx.

O que causa um erro 502 Bad Gateway no Nginx?

O Nginx frequentemente atua como proxy reverso, encaminhando requisições para aplicações de backend e retornando as respostas aos visitantes.

Se o serviço upstream não responder corretamente, o Nginx poderá retornar o código de status HTTP 502.

As causas comuns incluem:

• Serviços de backend que pararam ou falharam.
• Endereços IP, portas ou sockets Unix upstream incorretos.
• Falhas no PHP-FPM ou nos processos da aplicação.
• Problemas de permissão de acesso ao socket.
• Memória ou espaço em disco insuficiente.
• Conexões upstream inválidas ou encerradas prematuramente.

As verificações a seguir pressupõem que você tenha acesso SSH e permissão para administrar seu servidor Linux.

1. Verifique os logs de erro do Nginx

Os logs de erro do Nginx geralmente são a maneira mais rápida de identificar a causa de um erro 502.

Conecte-se ao servidor via SSH e execute:

sudo tail -n 50 /var/log/nginx/error.log

Isso exibe as 50 entradas mais recentes do log.

Para acompanhar os logs em tempo real durante o diagnóstico, use:

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

Recarregue a página afetada e observe se aparecem novas mensagens.

Sua configuração de hospedagem pode usar outro local para os logs.

Não altere as configurações do Nginx antes de identificar a causa provável.

2. Verifique se o serviço de backend está em execução

Um erro 502 costuma ocorrer porque a aplicação por trás do Nginx parou.

Para um serviço de aplicação gerenciado pelo systemd, execute:

sudo systemctl status myapp

Substitua myapp pelo nome real do seu serviço.

Para aplicações baseadas em PHP que usam PHP-FPM, o serviço pode ter um nome como:

sudo systemctl status php8.3-fpm

A versão instalada do PHP e o nome do serviço podem ser diferentes.

Se o serviço falhou, examine seus logs:

sudo journalctl -u myapp -n 50

Procure falhas, dependências ausentes, erros de configuração ou problemas relacionados à memória.

Reinicie o serviço somente depois de identificar e resolver a causa do problema.

3. Verifique a porta ou o socket upstream

O Nginx precisa encaminhar as requisições para o endereço correto do backend.

Por exemplo, a configuração de um proxy reverso pode conter:

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

Isso instrui o Nginx a encaminhar as requisições para uma aplicação HTTP que está escutando na porta 3000.

Verifique se há algum processo escutando nessa porta:

sudo ss -ltnp | grep ':3000'

Você também pode testar um backend HTTP diretamente:

curl -i http://127.0.0.1:3000/

Se o backend não estiver disponível, investigue a configuração do serviço antes de alterar o Nginx.

Verifique os sockets do PHP-FPM

O PHP-FPM geralmente usa sockets Unix ou portas TCP.

Uma configuração do Nginx pode conter:

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

Verifique se o socket configurado existe:

ls -l /run/php/

O caminho do socket deve corresponder à configuração listen do pool do PHP-FPM, e o Nginx precisa ter permissão para se conectar.

Importante: proxy_pass é usado para servidores upstream HTTP, enquanto fastcgi_pass é usado para serviços FastCGI, como o PHP-FPM. Eles não são intercambiáveis.

4. Verifique a memória e o espaço em disco do servidor

Aplicações de backend podem falhar ou parar de responder quando os recursos do servidor se esgotam.

Verifique a memória:

free -h

Verifique o espaço em disco:

df -h

Verifique os processos em execução:

top

Se uma aplicação foi encerrada por falta de memória, você poderá encontrar mensagens relevantes no journal do sistema:

sudo journalctl -k --since "1 hour ago"

Procure eventos de falta de memória ou mensagens sobre encerramento de processos.

Se o espaço em disco se esgotou, identifique o que o está consumindo antes de excluir arquivos.

5. Verifique as permissões do socket e os logs da aplicação

Às vezes, o backend está em execução, mas o Nginx não consegue se comunicar com ele.

Para sockets Unix, verifique o proprietário e as permissões:

ls -l /run/php/

Verifique também os diretórios no caminho até o socket se os logs indicarem um erro de permissão.

As permissões corretas dependem do usuário dos processos de trabalho do Nginx e da configuração do serviço de backend.

Evite conceder permissões amplas, como chmod 777. Em vez disso, ajuste a configuração do serviço ou pool correspondente para que os processos autorizados possam acessar o socket.

Se os logs de erro indicarem que o servidor upstream encerrou a conexão prematuramente, examine os logs da aplicação de backend em busca de falhas, exceções ou requisições malsucedidas.

6. Teste a configuração do Nginx

Configurações de proxy incorretas ou alterações na configuração também podem prejudicar a comunicação com o servidor upstream.

Antes de aplicar alterações, valide a configuração do Nginx:

sudo nginx -t

Se o teste for bem-sucedido, recarregue o Nginx:

sudo systemctl reload nginx

O recarregamento aplica alterações válidas na configuração sem reiniciar o serviço desnecessariamente.

Se o teste falhar, corrija primeiro o erro de configuração informado.

Não aumente os tempos limite do proxy nem os limites de buffer sem investigar. Esses ajustes não corrigirão um backend parado, um socket incorreto ou uma conexão recusada.

7. Confirme que o erro 502 foi corrigido

Depois de resolver a causa do problema, teste a URL afetada:

curl -I https://example.com

Substitua example.com pelo seu domínio real.

Uma requisição bem-sucedida geralmente retorna um status HTTP apropriado, como 200 OK, embora redirecionamentos e outras respostas válidas possam produzir códigos diferentes.

Abra também o site no navegador e examine novamente os logs de erro do Nginx.

Se o erro voltar quando houver mais carga, monitore o serviço de backend e o uso de recursos enquanto reproduz o problema.

Como evitar erros 502 no Nginx

Nem toda falha de backend pode ser evitada, mas uma boa administração do servidor reduz as indisponibilidades evitáveis.

• Monitore a disponibilidade do Nginx e dos serviços de backend.
• Examine os logs da aplicação após implantações.
• Configure políticas adequadas de recuperação dos serviços.
• Monitore o uso de memória, armazenamento e conexões.
• Valide as alterações de configuração antes de aplicá-las.
• Teste as aplicações diretamente antes de encaminhar o tráfego pelo Nginx.

Se uma aplicação precisar de mais recursos, meça seu uso real antes de decidir aumentar a capacidade do servidor.

Perguntas frequentes

Conclusão

A correção de um erro 502 Bad Gateway no Nginx começa pela identificação do motivo pelo qual a aplicação upstream não está respondendo corretamente.

Primeiro, verifique os logs de erro do Nginx, confirme que o serviço de backend está em execução e confira a porta ou o socket configurado. Em seguida, investigue limites de recursos, permissões e falhas da aplicação.

Na maioria dos casos, identificar a falha específica do servidor upstream é mais eficaz do que reiniciar repetidamente o Nginx ou alterar as configurações de tempo limite.