Um erro 502 em uma VPS quer dizer que o proxy recebeu uma resposta inválida, perdeu a conexão ou não conseguiu alcançar o serviço upstream. O diagnóstico fica mais rápido quando você separa navegador, Nginx, porta e processo da aplicação em vez de reiniciar tudo no primeiro minuto.
O que o código 502 está dizendo
O visitante fala com o Nginx, mas o Nginx precisa falar com outro processo, como Gunicorn, Node ou PHP-FPM. Se essa segunda conversa falha, o gateway devolve 502. O código não informa sozinho se a aplicação caiu, se a porta está errada ou se o processo fechou a conexão; por isso, o primeiro objetivo é descobrir qual elo está quebrado.
Faça o primeiro recorte antes de reiniciar
Reproduza o erro e anote horário, rota e host. Depois compare as camadas abaixo. A tabela evita tratar sintomas diferentes como se fossem a mesma falha.
| Sinal | Teste | Hipótese principal |
|---|---|---|
| 502 externo e curl local falha | curl http://127.0.0.1:8000/ | Aplicação, porta ou socket |
| 502 externo e curl local funciona | curl -I https://seu-dominio | Proxy, TLS ou configuração |
| 502 intermitente | Logs no mesmo minuto | Processo reiniciando, fila ou limite |
Confirme se a aplicação está viva
Comece pelo serviço que realmente atende o Nginx. Troque `app.service` pelo nome usado na sua unidade systemd e confira a porta definida em `proxy_pass`.
sudo systemctl status app.service --no-pager
sudo ss -lntp | grep -E ':8000|:8080'
curl -i --max-time 5 http://127.0.0.1:8000/Um status ativo não garante que a rota responde. O `ss` precisa mostrar o processo na porta esperada e o curl local deve retornar cabeçalhos HTTP. Se houver `Connection refused`, o Nginx está apontando para um processo parado ou para a porta errada.
Leia os logs do Nginx e do upstream
Capture os eventos do mesmo intervalo, porque uma linha isolada costuma esconder a sequência. O `connect() failed` aponta para acesso ao upstream; `upstream prematurely closed connection` aponta para encerramento antes de uma resposta completa.
sudo tail -n 80 /var/log/nginx/error.log
sudo journalctl -u app.service --since "10 minutes ago" --no-pager
sudo nginx -T | grep -nE 'server_name|proxy_pass|proxy_read_timeout'O primeiro comando mostra o erro que o cliente do Nginx encontrou. O segundo revela crash, traceback ou reinício do processo. O terceiro confirma a configuração carregada, não apenas o arquivo que você acredita ter editado.
Valide porta, socket e cabeçalho Host
Em setups com socket Unix, `proxy_pass http://unix:/run/app.sock:` exige que o arquivo exista e tenha permissões compatíveis. Em setups TCP, teste exatamente `127.0.0.1` e a porta. Uma aplicação que responde apenas para um host específico também pode produzir comportamento diferente entre o teste local e o domínio.
Compare o caminho externo com o upstream e preserve os cabeçalhos necessários. A presença de `X-Forwarded-Proto` não corrige um upstream desligado, mas evita que a aplicação gere redirecionamentos inconsistentes depois que a conectividade for recuperada.
Trate timeout e limite como causas diferentes
Se a conexão chega ao processo e a resposta demora, meça a rota antes de elevar `proxy_read_timeout`. Observe CPU, memória, disco e fila. Um 502 imediato pede conectividade ou processo; um 504 depois de vários segundos sugere espera excedida. Reiniciar pode aliviar uma fila, mas não explica por que ela se formou.
Corrija com a menor mudança reversível
Depois de identificar a camada, altere uma variável: restaure a porta correta, corrija a unidade systemd ou ajuste a rota que falha. Rode `sudo nginx -t` antes de recarregar. Guarde o arquivo anterior e valide com curl externo e local; assim, uma correção não cria um segundo incidente difícil de separar do primeiro.
Se o problema foi uma aplicação em crash loop, acompanhe o journal por alguns minutos. Se foi um socket, valide dono e modo do arquivo. Se foi configuração, confira o bloco de servidor efetivamente carregado. Para complementar este procedimento com continuidade, leia o guia de backup local versus backup externo em VPS.
Evite que o 502 volte sem explicação
Registre nome do serviço, porta, caminho do log, comando de verificação e condição de rollback. Um health check simples deve distinguir processo ouvindo de aplicação pronta. Também vale medir reinícios e memória, porque o padrão “funciona depois do reboot” costuma esconder vazamento, limite de arquivo ou dependência indisponível.
Quando o incidente envolve demora de rede até a VPS, o próximo recorte é diferente: compare RTT, rota e tempo de resposta HTTP com o método descrito em como testar a latência real de uma VPS no Brasil.
Conclusão: prove a camada antes de mudar o servidor
O caminho mais curto para um 502 é confirmar processo, porta, logs e configuração na ordem em que a requisição passa por eles. Depois da correção, repita o teste local e externo, anote o resultado e deixe um comando reproduzível para o próximo plantão. Se você não consegue dizer qual camada falhou, ainda não há evidência suficiente para trocar a VPS.
Perguntas frequentes
Um erro 502 sempre é culpa do Nginx?
Não. O Nginx só informa que não conseguiu obter uma resposta válida do upstream. A causa pode estar no processo da aplicação, na porta configurada, em um socket inacessível, em timeout ou em uma falha de rede local. Compare o erro do navegador com curl local, systemctl status e o error.log para separar a camada que falhou.
Qual comando confirma se a aplicação está ouvindo?
Use ss -lntp para portas TCP e ss -lx para sockets Unix. O endereço e a porta precisam coincidir com proxy_pass. Em seguida, faça curl http://127.0.0.1:PORTA/ na própria VPS. Se o curl local falhar, investigar o Nginx primeiro apenas atrasa o diagnóstico.
Devo aumentar proxy_read_timeout?
Só depois de confirmar que a aplicação está viva e que a operação realmente pode durar mais. Aumentar timeout para esconder processo travado mantém conexões abertas e pode piorar a fila. Registre o tempo esperado da rota, observe o journal e trate a causa do atraso antes de alterar o limite.
Como diferenciar 502 de 504?
Em geral, 502 indica resposta inválida, conexão recusada ou fechamento inesperado do upstream; 504 indica que o gateway esperou e não recebeu resposta dentro do prazo. A distinção não substitui os logs, mas orienta o primeiro recorte: conectividade e processo para 502, duração e timeout para 504.