Erro 502 Bad Gateway na aplicação da VPS: o que fazer

O erro 502 Bad Gateway quer dizer que o proxy na frente da aplicação (quase sempre o Nginx) recebeu o pedido do navegador, mas não conseguiu resposta da aplicação. As causas mais comuns são: a aplicação está parada, o contêiner dela parou, a porta configurada no proxy está errada ou a aplicação ainda está subindo. Comece pelo log de erros do Nginx: ele diz qual endereço tentou e por que falhou.

Atenção: segurança da sua VPS. Os comandos no SSH mexem direto no servidor e são executados por sua conta e risco. Confira cada comando antes de rodar e, se puder, crie um snapshot da VPS antes de começar.

Sintomas

• O navegador mostra 502 Bad Gateway, muitas vezes com nginx embaixo.
• O erro começou depois de reiniciar a VPS, atualizar a aplicação ou mudar a configuração.
• No log do Nginx aparece connect() failed (111: Connection refused) while connecting to upstream ou upstream prematurely closed connection.

Os comandos deste artigo valem para o Ubuntu e o Debian, os sistemas das VPS da StayCloud, e supõem que você entrou como root (veja "Como acessar sua VPS por SSH pelo terminal (Linux, Windows e Mac)"). Os exemplos usam o Nginx; outro proxy segue a mesma lógica, com o log e a configuração dele. Primeiro, leia o fim do log de erros:

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

A linha do erro traz o upstream, que é o endereço da aplicação que o Nginx tentou, como http://127.0.0.1:3000/.

Causa 1: a aplicação está parada

Como confirmar: veja se algum programa atende na porta do upstream (troque <PORTA> pela porta do log):

ss -tlnp | grep <PORTA>

Se não aparece nada, a aplicação não está rodando. Se ela roda como serviço do sistema, veja o estado:

systemctl status <SERVICO>

Como resolver: inicie o serviço e deixe-o ligando junto com a VPS:

systemctl start <SERVICO>
systemctl enable <SERVICO>

Se ele não sobe, veja o motivo com journalctl -u <SERVICO> -n 50. Se a aplicação para sozinha de tempos em tempos, pode ser falta de memória: veja "VPS lenta ou travando: o que verificar". O passo a passo dos serviços está em "Como ver e gerenciar serviços na VPS via SSH".

Causa 2: o contêiner parou

Como confirmar: se a aplicação roda no Docker, liste todos os contêineres, inclusive os parados:

docker ps -a

Na coluna STATUS, Exited quer dizer parado e Restarting quer dizer que ele cai e tenta voltar sem parar. Veja o motivo no log do contêiner:

docker logs --tail 50 <CONTEINER>

Como resolver: corrija o que o log aponta e inicie o contêiner:

docker start <CONTEINER>

Para ele voltar sozinho depois de um reinício da VPS, use docker update --restart unless-stopped <CONTEINER>. Se você usa Docker Compose, rode docker compose up -d na pasta do projeto.

Causa 3: a porta ou o endereço no proxy está errado

Como confirmar: veja para onde o Nginx manda os pedidos:

grep -R "proxy_pass" /etc/nginx/sites-enabled/ /etc/nginx/conf.d/

Compare com a porta em que a aplicação está ouvindo, que aparece no ss -tlnp. Exemplo de erro: proxy_pass http://127.0.0.1:3000; com a aplicação ouvindo na 8080. Se a aplicação está num contêiner, a porta precisa estar publicada para o Nginx do sistema chegar nela: confira a coluna PORTS do docker ps.

Como resolver: corrija o proxy_pass no arquivo do site, teste a configuração e recarregue o Nginx:

nginx -t
systemctl reload nginx

O nginx -t deve terminar com test is successful. A diretiva está explicada na documentação oficial do Nginx, em nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass.

Causa 4: a aplicação ainda está subindo

Como confirmar: o 502 aparece logo depois de reiniciar a VPS, a aplicação ou o contêiner, e some sozinho depois de um tempo. Acompanhe o log enquanto ela sobe:

journalctl -u <SERVICO> -f

Ou, no Docker, docker logs -f <CONTEINER>. Aperte Ctrl + C para parar de acompanhar.

Como resolver: espere a aplicação terminar de subir; algumas levam um ou dois minutos. Se o 502 não some e o log mostra a aplicação reiniciando em ciclo, ela está caindo ao subir: trate como a causa 1 ou a causa 2.

Quando chamar o Suporte

Na VPS, você tem acesso root e cuida do que instala; o suporte da StayCloud cuida da infraestrutura: a VPS ligada, a rede e o painel, e não configura nem depura a sua aplicação. Veja "Perguntas frequentes sobre o que o suporte da StayCloud faz". Abra um chamado se a VPS reinicia ou perde a rede sozinha, ou se o 502 é num app pronto instalado pelo painel (como o n8n) e você não mexeu na configuração dele.

No chamado, informe o endereço que dá erro, o IP da VPS ou o nome dela no painel, o horário, as últimas linhas do /var/log/nginx/error.log, a saída de docker ps -a ou de systemctl status da aplicação e o que você já tentou. O passo a passo está em "Como abrir um chamado no Suporte".

Relacionados

• Como ver e gerenciar serviços na VPS via SSH
• Como instalar o Docker na VPS via SSH
• VPS lenta ou travando: o que verificar
• Como reiniciar sua VPS pelo painel
• Como acessar sua VPS por SSH pelo terminal (Linux, Windows e Mac)
• Perguntas frequentes sobre o que o suporte da StayCloud faz
• Como abrir um chamado no Suporte