Site com erro 502 Bad Gateway: diagnóstico e correção no Nginx

15 min de leitura  ·  Guia técnico

Erro 502 Bad Gateway no Nginx ocorre quando o servidor web não consegue obter uma resposta válida do processo backend — como PHP-FPM, Gunicorn ou Node.js. O diagnóstico correto exige verificar logs, status dos serviços e configuração do bloco upstream. Veja abaixo como identificar a causa raiz e corrigir definitivamente.

Pré-requisitos

• Acesso root ou sudo ao servidor (Debian 12, Ubuntu 24.04 LTS ou Rocky Linux 9)
• Nginx 1.24+ instalado e configurado como proxy reverso ou servidor FastCGI
• Backend em execução: PHP-FPM 8.3, Gunicorn, Node.js ou outro processo upstream
• Acesso ao terminal via SSH — veja como acessar servidores VPS Linux da AviraHost
• Permissão para ler logs em /var/log/nginx/ e /var/log/php8.3-fpm.log

Erro 502 Bad Gateway no Nginx: entendendo o que acontece

O erro 502 Bad Gateway é gerado pelo Nginx quando ele age como proxy e o servidor upstream não responde — ou responde com dados inválidos. Diferente do erro 503 (serviço indisponível), o 502 indica especificamente uma falha de comunicação entre o Nginx e o processo backend, não uma sobrecarga do próprio Nginx.

O fluxo típico é: cliente → Nginx → PHP-FPM (ou outro backend). Se o PHP-FPM não responder dentro do timeout configurado, ou se o socket Unix não existir, o Nginx retorna 502 imediatamente ao cliente. Isso significa que o problema raramente está no Nginx em si — ele está apenas reportando a falha do backend.

As três causas mais frequentes em produção são:

• Processo backend parado: PHP-FPM, Gunicorn ou Node.js travou ou foi encerrado inesperadamente.
• Socket Unix ou porta TCP incorretos: o fastcgi_pass ou proxy_pass no Nginx aponta para um endereço diferente do que o backend está escutando.
• Timeout excedido: o backend está lento demais e o Nginx encerra a conexão antes de receber resposta.

Diagnóstico do erro 502: lendo os logs do Nginx e do backend

O primeiro passo para resolver qualquer falha de gateway no Nginx é ler os logs de erro com atenção. O log padrão do Nginx fica em /var/log/nginx/error.log e costuma indicar exatamente qual upstream falhou.

Execute o comando abaixo para ver as últimas ocorrências do erro 502 em tempo real:

tail -f /var/log/nginx/error.log | grep -i "502\|upstream\|connect\|timed out"

Saída típica quando o PHP-FPM está parado:

2024/11/14 03:22:11 [error] 1234#1234: *89 connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) while connecting to upstream, client: 203.0.113.5, server: exemplo.com.br, request: "GET / HTTP/1.1", upstream: "fastcgi://unix:/run/php/php8.3-fpm.sock:", host: "exemplo.com.br"

A mensagem "No such file or directory" confirma que o socket Unix não existe — o PHP-FPM está parado ou nunca foi iniciado. Já a mensagem "upstream timed out" indica que o processo existe mas não responde a tempo.

Para verificar o log do PHP-FPM diretamente:

tail -100 /var/log/php8.3-fpm.log

Procure por entradas como "WARNING: [pool www] seems busy", que indicam esgotamento de workers, ou "ERROR: failed to ptrace", que indicam problemas de permissão.

Verificando o status dos serviços backend

Após analisar os logs, confirme o status do processo upstream com o systemd. Este passo elimina dúvidas sobre se o serviço está ativo, em falha ou reiniciando em loop.

Para PHP-FPM 8.3 no Debian 12 ou Ubuntu 24.04:

systemctl status php8.3-fpm

● php8.3-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded (/lib/systemd/system/php8.3-fpm.service; enabled; preset: enabled)
     Active: active (running) since Wed 2024-11-13 22:10:05 UTC; 5h 12min ago
    Process: 1021 ExecStartPre=/usr/lib/php/php8.3-fpm-checkconf (code=exited, status=0/SUCCESS)
   Main PID: 1035 (php-fpm8.3)
     Status: "Processes active: 0, idle: 5, Requests: 1842, slow: 0, Traffic: 0req/sec, Load: 0.00"

Se o status mostrar "failed" ou "inactive", reinicie o serviço:

systemctl restart php8.3-fpm

Para aplicações Node.js gerenciadas pelo PM2:

pm2 status
pm2 restart all

Para aplicações Python com Gunicorn gerenciadas pelo systemd:

systemctl status gunicorn
systemctl restart gunicorn

Após reiniciar, recarregue a página no navegador e verifique se o erro 502 desapareceu. Se voltou em segundos, o problema é mais profundo — continue o diagnóstico.

Corrigindo a configuração do bloco upstream no Nginx

Uma das causas mais silenciosas do 502 em configuração Nginx é a divergência entre o socket/porta configurado no PHP-FPM e o endereço referenciado no bloco do Nginx. O serviço pode estar rodando perfeitamente, mas o Nginx tenta se conectar ao lugar errado.

Primeiro, descubra onde o PHP-FPM está escutando:

grep -r "^listen" /etc/php/8.3/fpm/pool.d/

/etc/php/8.3/fpm/pool.d/www.conf:listen = /run/php/php8.3-fpm.sock

Agora verifique o bloco do Nginx para o site em questão:

grep -r "fastcgi_pass\|proxy_pass" /etc/nginx/sites-enabled/

/etc/nginx/sites-enabled/exemplo.com.br:    fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Os dois valores devem ser idênticos. Se o PHP-FPM usa socket Unix, o Nginx deve usar unix:/caminho/do/socket. Se usa porta TCP (ex: 127.0.0.1:9000), o Nginx deve referenciar a mesma porta.

Caso use socket Unix, verifique também as permissões do arquivo de socket:

ls -la /run/php/php8.3-fpm.sock

srw-rw---- 1 www-data www-data 0 Nov 14 03:10 /run/php/php8.3-fpm.sock

O usuário do worker do Nginx (geralmente www-data) precisa ter permissão de leitura e escrita no socket. Se necessário, ajuste no pool do PHP-FPM:

; /etc/php/8.3/fpm/pool.d/www.conf
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Após qualquer alteração no PHP-FPM, recarregue o serviço:

systemctl reload php8.3-fpm

E teste a configuração do Nginx antes de recarregar:

nginx -t && systemctl reload nginx

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Ajustando timeouts para evitar 502 em horários de pico

Quando o erro 502 ocorre intermitentemente — especialmente sob carga — o problema geralmente é timeout ou esgotamento de workers. O Nginx encerra a conexão com o backend antes que ele termine de processar a requisição.

Edite o bloco do servidor no Nginx e ajuste os parâmetros de timeout:

server {
    listen 80;
    server_name exemplo.com.br;

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

        fastcgi_connect_timeout 60s;
        fastcgi_send_timeout    120s;
        fastcgi_read_timeout    120s;
        fastcgi_buffer_size     128k;
        fastcgi_buffers         4 256k;
        fastcgi_busy_buffers_size 256k;
    }
}

Para aplicações que usam proxy_pass (Node.js, Gunicorn, etc.), os parâmetros equivalentes são:

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_connect_timeout  60s;
    proxy_send_timeout     120s;
    proxy_read_timeout     120s;

    upstream backend {
        server 127.0.0.1:8000;
        keepalive 32;
    }
}

A diretiva keepalive 32 no bloco upstream reutiliza conexões TCP abertas, reduzindo o overhead de handshake e diminuindo a probabilidade de timeout sob carga.

Para aumentar os workers do PHP-FPM, edite o pool:

; /etc/php/8.3/fpm/pool.d/www.conf
pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
pm.max_requests = 500

O valor de pm.max_children deve ser calculado com base na RAM disponível. Uma regra prática: divida a RAM disponível para o PHP pelo consumo médio de cada processo (geralmente 30–60 MB). Em um servidor com 2 GB dedicados ao PHP, um valor entre 30 e 50 é razoável.

Para dicas adicionais de otimização do servidor, consulte as Dicas de Otimização de Servidores Linux.

Configurando reinicialização automática com systemd

Para garantir alta disponibilidade do backend e evitar que uma falha pontual do PHP-FPM cause 502 prolongado, configure o systemd para reiniciar o serviço automaticamente em caso de falha.

Crie um arquivo de override para o serviço do PHP-FPM:

systemctl edit php8.3-fpm

Adicione o seguinte conteúdo no editor que abrir:

[Service]
Restart=on-failure
RestartSec=5s
StartLimitIntervalSec=60s
StartLimitBurst=3

Salve e recarregue o daemon:

systemctl daemon-reload
systemctl restart php8.3-fpm

Com essa configuração, se o PHP-FPM travar, o systemd o reiniciará automaticamente após 5 segundos — limitando a janela de 502 a poucos segundos em vez de minutos ou horas.

Atenção: o parâmetro StartLimitBurst=3 impede loops infinitos de reinicialização. Se o serviço falhar mais de 3 vezes em 60 segundos, o systemd para de tentar e você precisará investigar a causa raiz manualmente.

Problemas comuns e como resolver

Sintoma: 502 imediato ao acessar qualquer página do site

Causa: O processo backend (PHP-FPM, Gunicorn ou Node.js) está completamente parado. O socket Unix não existe ou a porta TCP não está sendo escutada.
Solução: Execute systemctl status php8.3-fpm e verifique se o serviço está ativo. Se estiver parado, inicie com systemctl start php8.3-fpm. Confirme que o socket foi criado com ls /run/php/php8.3-fpm.sock. Se o arquivo não aparecer, verifique o log do PHP-FPM em /var/log/php8.3-fpm.log para identificar erros de inicialização.

Sintoma: 502 apenas em páginas específicas ou após upload de arquivos grandes

Causa: O timeout do Nginx está configurado abaixo do tempo necessário para processar a requisição. Páginas que executam operações longas (geração de relatórios, processamento de imagens, importações) ultrapassam o limite padrão de 60 segundos.
Solução: Aumente fastcgi_read_timeout para o bloco específico da aplicação. Para uploads, ajuste também client_max_body_size e client_body_timeout no bloco do servidor. Considere mover operações longas para filas assíncronas (Redis Queue, Celery) para não bloquear o worker do PHP-FPM.

Sintoma: 502 com mensagem "upstream sent invalid header" no log do Nginx

Causa: O backend está respondendo, mas com cabeçalhos HTTP malformados ou com saída antes dos cabeçalhos (output buffering desativado no PHP, por exemplo). Também ocorre quando o PHP retorna um erro fatal antes de enviar qualquer cabeçalho.
Solução: Ative o log de erros do PHP com log_errors = On e error_log = /var/log/php8.3-errors.log no php.ini. Verifique o log para identificar o erro fatal. Certifique-se de que nenhum arquivo PHP imprime conteúdo antes de chamar header(). Ative fastcgi_intercept_errors on no Nginx para capturar esses erros.

Sintoma: 502 após atualização do PHP ou migração de servidor

Causa: O caminho do socket mudou com a nova versão do PHP. Por exemplo, ao migrar do PHP 8.1 para o PHP 8.3, o socket passa de /run/php/php8.1-fpm.sock para /run/php/php8.3-fpm.sock, mas a configuração do Nginx ainda aponta para o caminho antigo.
Solução: Execute grep -r "fastcgi_pass" /etc/nginx/sites-enabled/ e compare com grep "^listen" /etc/php/8.3/fpm/pool.d/www.conf. Atualize todos os blocos do Nginx para o novo caminho e execute nginx -t && systemctl reload nginx.

Perguntas frequentes sobre erro 502 Bad Gateway no Nginx

O que causa o erro 502 Bad Gateway no Nginx?

O erro 502 Bad Gateway ocorre quando o Nginx não consegue obter uma resposta válida do servidor upstream, que pode ser o PHP-FPM, Gunicorn, Node.js ou outro processo backend. As causas mais comuns são: processo backend parado, socket Unix inexistente, timeout de resposta excedido ou configuração incorreta do bloco upstream no Nginx. O log em /var/log/nginx/error.log sempre indica qual upstream falhou e o motivo específico.

Como verificar se o PHP-FPM está causando o erro 502?

Execute systemctl status php8.3-fpm para verificar se o serviço está ativo. Em seguida, confira o log em /var/log/php8.3-fpm.log e o log de erros do Nginx em /var/log/nginx/error.log. Se o PHP-FPM estiver parado ou com workers esgotados, reinicie com systemctl restart php8.3-fpm e ajuste o parâmetro pm.max_children no pool correspondente para suportar mais requisições simultâneas.

Erro 502 aparece só em horários de pico — o que fazer?

Esse comportamento indica esgotamento de workers do backend sob carga. No PHP-FPM, aumente pm.max_children e considere mudar o gerenciador de processos de dynamic para ondemand ou static conforme a RAM disponível. No Nginx, ajuste proxy_read_timeout e fastcgi_read_timeout para valores maiores, e habilite keepalive no bloco upstream para reutilizar conexões TCP e reduzir latência sob carga.

É possível ter erro 502 mesmo com PHP-FPM rodando?

Sim. O PHP-FPM pode estar ativo mas com o socket Unix ou porta TCP configurada de forma diferente do que o Nginx espera. Verifique se o parâmetro listen no pool do PHP-FPM bate exatamente com o fastcgi_pass ou proxy_pass no bloco do Nginx. Permissões incorretas no arquivo de socket também causam 502 mesmo com o serviço em execução — o usuário www-data precisa ter acesso de leitura e escrita ao socket.

Como evitar que o erro 502 volte a acontecer em produção?

Configure monitoramento do processo backend com systemd usando a opção Restart=on-failure para reinicialização automática em caso de falha. Ajuste os timeouts do Nginx de acordo com o tempo real de resposta da aplicação medido em condições normais. Implemente health checks no bloco upstream do Nginx e use logs estruturados para detectar picos de latência antes que causem 502 em cascata. Ferramentas como Netdata ou Prometheus com alertas no Grafana ajudam a identificar tendências antes que virem incidentes.

Conclusão

• Leia os logs primeiro: /var/log/nginx/error.log sempre indica o upstream que falhou e o motivo — "No such file or directory" aponta para socket inexistente, "timed out" aponta para timeout.
• Valide a correspondência de sockets: confirme que o fastcgi_pass no Nginx e o listen no pool do PHP-FPM apontam para o mesmo endereço, com permissões corretas para o usuário www-data.
• Previna recorrências: configure Restart=on-failure no systemd, ajuste pm.max_children com base na RAM disponível e defina timeouts realistas no Nginx para evitar 502 em horários de pico.

Leia também

• Solucionar erro 500 no WordPress: diagnóstico rápido e correção definitiva
• Como Instalar e Configurar o Nginx como Servidor Web no VPS Linux
• Nginx vs Apache: Qual é o Melhor para Hospedagem Linux em 2026?

Precisa de ajuda com Nginx e configuração de servidor?

Configurar Nginx como proxy reverso com PHP-FPM exige atenção a detalhes de socket, permissões e timeouts que variam conforme a aplicação e a carga do servidor. Um VPS com suporte técnico especializado pode reduzir significativamente o tempo de resolução desses problemas em produção.

Conheça os planos de VPS da AviraHost com suporte técnico