Troubleshooting avançado de erro 500 no cPanel: do rastreio de logs à compatibilidade do runtime

Quem gerencia aplicações web no cPanel sabe que o código HTTP 500 (Internal Server Error) é apenas o sintoma superficial. Por trás de uma mensagem genérica no navegador, a causa real pode ir desde uma regra malformada no .htaccess até falhas de segmentação no interpretador ou limites de processos no CloudLinux.

Recentemente, passei por uma depuração completa em um ambiente cPanel onde precisei mapear exatamente onde cada camada grava seus erros e como diagnosticar incompatibilidades de runtime PHP.

Abaixo, compartilho o mapa de logs, a metodologia de depuração via linha de comando e as matrizes de compatibilidade.

1. O fluxo de execução e o mapa de logs em 4 camadas#

Para não perder tempo abrindo arquivos aleatórios, sigo o caminho da requisição: WAF -> Webserver -> Process Manager (FPM/LSAPI) -> Aplicação.

Nível 1: Aplicação (PHP runtime)#

Se o interpretador PHP iniciou a execução normalmente mas quebrou por erro de sintaxe, função inexistente ou estouro de memória, ele grava no diretório da conta:

• Caminho padrão: /home/$USER/public_html/error_log
• Log configurado por vhost: /home/$USER/logs/$DOMAIN.php.error.log
• Comando de monitoramento:

  tail -f /home/$USER/public_html/error_log

• Erros comuns:
• PHP Fatal error: Uncaught Error: Call to undefined function...
• PHP Parse error: syntax error, unexpected...
• Allowed memory size of X bytes exhausted

Nível 2: Webserver (Apache / LiteSpeed)#

Se o erro 500 ocorre antes do PHP ser chamado (como regras inválidas no .htaccess ou permissões incorretas), o log da aplicação fica vazio. A resposta está nos logs globais do web server:

• Apache Global: /usr/local/apache/logs/error_log
• LiteSpeed: /usr/local/lsws/logs/error.log ou /usr/local/lsws/logs/stderr.log
• Erros comuns:
• .htaccess: Invalid command 'XYZ': Diretivas desconhecidas ou módulos ausentes.
• Premature end of script headers ou End of script output before headers: Falha de permissão (deve ser 0644 para arquivos e 0755 para pastas) ou encerramento abrupto do binário.
• SoftException in Application.cpp: Mismatch de UID/GID em módulos de segurança como suPHP.

Nível 3: Process manager (PHP-FPM)#

Quando o Apache atua como proxy reverso para pools FastCGI/FPM:

• Caminho (EasyApache): /opt/cpanel/ea-phpXX/root/usr/var/log/php-fpm/error.log (onde XX é a versão do PHP, ex: ea-php81)
• Erros comuns:
• server reached max_children: Pool esgotado e requisições caindo por timeout.
• child X exited on signal 11 (SIGSEGV): Falha de segmentação (Segmentation Fault), geralmente ligada a extensões corrompidas ou bugs de Opcache.
• child X exited on signal 9 (SIGKILL): Processo terminado forçadamente por limites do sistema.

Nível 4: WAF (ModSecurity) e limites de kernel (CloudLinux LVE)#

Se o erro persistir sem rastro nos logs acima:

• ModSecurity: Se configurado com regras restritivas, pode abortar conexões com código 500.
• Log: /usr/local/apache/logs/modsec_audit.log
• CloudLinux LVE / OOM: Quando o processo atinge os limites de memória física (MEMPHY) ou processos máximos (NPROC).
• Comandos: lveinfo --user $USER, lvetop ou via dmesg | grep -i "lve".

2. Matriz de diagnóstico rápido#

3. Investigação de baixo nível via CLI#

Quando os logs são inconclusivos ou o erro ocorre de forma intermitente:

Rastreamento de chamadas com strace#

Para identificar qual arquivo ou socket o processo tentou abrir imediatamente antes de falhar:

strace -p $(pgrep -u $USER php-fpm | head -1) -s 128 -e trace=open,stat,connect

• ENOENT: Arquivo ou biblioteca não encontrada (erros de autoloader).
• EACCES: Permissão negada no CageFS ou sistema de arquivos.
• EAGAIN: Sockets ou threads temporariamente indisponíveis.

Monitoramento global em tempo real#

tail -f /usr/local/apache/logs/error_log | grep "internal server error"

Inodes esgotados (df -i)#

Um detalhe frequentemente ignorado é o esgotamento de inodes (df -i). Se o disco estiver com inodes em 100%, o PHP não consegue gravar arquivos de sessão em /var/cpanel/php/sessions ou /tmp, disparando erros 500 silenciosos.

4. Análise de compatibilidade de runtime (WordPress vs PHP)#

Ao atualizar ambientes WordPress via terminal:

[[ -f wp-config.php ]] && wp core version --allow-root

Identificada a versão do core, o próximo passo é conferir a compatibilidade com o interpretador PHP:

• PHP 7.4: Descontinuado (EOL). O uso de bibliotecas modernas no core gera avisos constantes de depreciação.
• PHP 8.0: Compatível, mas fora do ciclo de suporte ativo.
• PHP 8.1 / 8.2 (Recomendado): Ponto ideal de estabilidade e ganhos de desempenho com o compilador JIT (Just-In-Time).
• PHP 8.3: Compatível, exigindo atenção a plugins legados que possam quebrar devido a readonly classes ou mudanças na função unserialize().
• PHP 8.4+: Suporte experimental, onde avisos E_DEPRECATED podem se comportar como E_ERROR.

Conclusão: cuidados essenciais na prática#

Ao atualizar uma aplicação para o PHP 8.2 ou superior:

1. Mudanças na Zend Engine: O PHP 8.x converteu diversos warnings antigos em Fatal Errors (como leitura de propriedades em variáveis nulas).
2. Extensões necessárias no EasyApache: Valide se os módulos essenciais estão ativos:

   php -m | grep -E "mysqli|gd|imagick|intl|curl|mbstring|zip|dom|xmlreader|simplexml"

1. Teste de sintaxe do core:

   php -d display_errors=On wp-includes/version.php

1. Resquícios de .htaccess: Após trocar a versão do PHP pelo cPanel, certifique-se de que o .htaccess não contém linhas antigas de AddHandler (como ea-php74) apontando para sockets inexistentes, o que causa erro 500 imediato no Apache.

Veja também

Servidores O mistério dos arquivos deletados: como rastrear remoções no cPanel, FTP e na camada PHP

Infraestrutura Anatomia de um deadlock silencioso no CloudLinux e cPanel: processos fantasmas, travas de sessão e filas TCP

Servidores Troubleshooting cPanel: como tratei a tela branca ao acessar contas via WHM (xfercpanel)

Este post está licenciado sob CC BY-NC.