Erro 500: qual log ler primeiro para achar a causa
Roteiro de triagem baseado na documentação oficial do cPanel: qual arquivo responde cada sintoma, como transformar a linha do stack trace em nome de plugin e o que dizer ao cliente enquanto o site volta.

Resposta curta: a causa está, quase sempre, em um de três logs lidos nesta ordem: Errors no cPanel, o arquivo error_log da pasta do site e wp-content/debug.log depois de ligar WP_DEBUG_LOG. A tela Errors do cPanel sozinha engana porque mostra só as entradas recentes do log do servidor web.
Neste artigo
- O sintoma já restringe onde olhar
- Por que a tela Errors do cPanel engana quando lida sozinha
- A ordem de leitura que resolve na primeira passada
- Da linha de log ao nome do plugin, do tema ou da versão de PHP
- Desativar só o culpado, não o site inteiro
- Log vazio também diz algo: o PHP não executou ou não conseguiu escrever
- Checklist para ter log de erro ligado antes do próximo incidente
- O que dizer ao cliente enquanto o site volta
Chamada de cliente com site fora do ar tem duas respostas possíveis. A ruim é desativar todos os plugins, trocar o tema, subir backup de três dias atrás e rezar. A boa é abrir o log, ler uma linha e saber o nome da pasta culpada em dois minutos.
A diferença entre as duas não é conhecimento de PHP. É saber qual arquivo responde qual sintoma, e em que ordem abrir.
O sintoma já restringe onde olhar
Antes de abrir qualquer coisa, classifique o que o navegador está mostrando. Cada sintoma tem um conjunto pequeno de origens plausíveis, e isso corta metade do caminho.
| Sintoma no navegador | Onde a resposta costuma estar | Assinatura típica |
|---|---|---|
| Tela totalmente branca, sem texto | error_log da pasta do site ou debug.log |
PHP Fatal error com caminho de arquivo |
| HTTP 500 com página de erro do servidor | log de erro do servidor web (Errors no cPanel) e error_log |
erro de sintaxe em .htaccess, fatal de PHP, permissão |
| "Ocorreu um erro crítico no site" (tela do WordPress) | debug.log, depois de ligar WP_DEBUG_LOG |
Uncaught Error ou Uncaught TypeError |
| HTTP 502 ou 504 | log do servidor web; provável timeout ou processo morto | Gateway timeout, premature end of script |
| Erro de conexão com o banco | error_log e credenciais do wp-config.php |
Error establishing a database connection |
| 404 em arquivos estáticos, imagens quebradas | Errors no cPanel | linhas de arquivo não encontrado |
A tela de "erro crítico" é a mais mal interpretada. Ela não é um erro genérico do WordPress: é o WordPress capturando um erro fatal de PHP e trocando a tela branca por uma mensagem amigável. O detalhe existe, só não está na tela. Está no log.
Por que a tela Errors do cPanel engana quando lida sozinha
A interface Errors do cPanel é o primeiro lugar em que todo mundo clica, e com razão: está a um clique, não pede terminal, não pede FTP. O problema é o que ela cobre.
Segundo a documentação oficial do cPanel, a interface exibe as entradas mais recentes do log de erro do site, com o objetivo de ajudar a identificar coisas como links quebrados, arquivos ausentes e problemas de permissão. Ela é uma janela para o log de erro do servidor web, com um limite de entradas: o que é antigo sai da lista.
Duas consequências práticas:
- Se o incidente aconteceu ontem e o site recebe tráfego, o fatal pode já ter rolado para fora da janela. Você olha, vê 404 de favicon, conclui que "não tem erro nenhum" e volta a chutar.
- O erro fatal do PHP pode não estar ali. Onde o PHP grava as mensagens depende da configuração do handler (
log_errorseerror_log). Em muitos ambientes de hospedagem compartilhada, o PHP escreve num arquivoerror_logdentro do diretório do próprio site, não no log do servidor web que a interface mostra.
A leitura correta da tela Errors é: ela confirma que houve erro e dá o horário, o IP e às vezes o arquivo. Ela raramente entrega o stack trace completo. Trate como triagem, não como diagnóstico.
A ordem de leitura que resolve na primeira passada
A ordem importa porque cada passo é mais caro que o anterior. Comece pelo que não exige mexer em arquivo do cliente.
Errors no cPanel dá o horário e a primeira pista
Abra Metrics > Errors. Procure a entrada mais recente que coincide com o horário em que o cliente diz que o site caiu. Duas coisas valem ouro aqui: o timestamp e qualquer caminho de arquivo na mensagem.
Se a mensagem citar .htaccess, pare. Erro de sintaxe em .htaccess derruba o site com 500 sem nenhum PHP envolvido, e a correção é renomear o arquivo para .htaccess.off e gerar de novo os links permanentes depois.
`error_log` na pasta do site, onde o fatal do PHP normalmente aparece
Este é o arquivo que resolve a maioria dos casos de tela branca. Ele fica no mesmo diretório em que o erro aconteceu, o que é uma informação em si: um error_log dentro de wp-content/plugins/algum-plugin/ já aponta o culpado antes de você ler uma linha.
Por SSH:
# localizar todos os error_log modificados nos últimos 2 dias
find ~/public_html -name "error_log" -mtime -2
# ler as últimas linhas do log da raiz do site
tail -n 50 ~/public_html/error_log
# filtrar só os fatais
grep -i "fatal error" ~/public_html/error_log | tail -n 5
Sem SSH, o Gerenciador de Arquivos do cPanel abre o mesmo arquivo. Ative a exibição de arquivos ocultos, clique em error_log e use "View". Arquivos de log grandes travam o editor do navegador: prefira "Download" se passar de alguns megabytes.
`wp-content/debug.log`, para o erro que o WordPress captura e esconde
Se o log do servidor não tem nada e o site mostra "erro crítico", o caminho é ligar o log do próprio WordPress. No wp-config.php, acima da linha /* That's all, stop editing! */:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
O ponto crítico é o par WP_DEBUG_DISPLAY em false com display_errors em 0. Sem isso, você liga o debug em produção e passa a imprimir caminho de arquivo e nome de função na cara do visitante, o que é vazamento de informação e péssima aparência para o cliente.
Depois de ligar, reproduza o erro (acesse a URL que falha, ou o painel) e leia:
tail -n 40 ~/public_html/wp-content/debug.log
Se nada aparece nem aqui, o PHP não chegou a executar. Volte ao passo 1: é servidor web, .htaccess, permissão ou limite de recurso.
Da linha de log ao nome do plugin, do tema ou da versão de PHP
Uma linha de fatal tem três informações úteis: o tipo de erro, o caminho do arquivo e o número da linha. O caminho é o que converte log em ação.
Exemplo fictício, escrito aqui para ilustrar o formato:
[15-Sep-2025 14:22:03 UTC] PHP Fatal error: Uncaught Error: Call to undefined
function exemplo_helper() in /home/usuario/public_html/wp-content/plugins/
exemplo-slider/includes/render.php:88
Leitura, da direita para a esquerda:
wp-content/plugins/exemplo-slider/identifica o culpado. É o slug do plugin, o mesmo nome que você usa no WP-CLI.render.php:88é onde reproduzir, se for o caso de abrir o código.Call to undefined functionnormalmente é dependência ausente: o plugin espera outro plugin, uma extensão de PHP, ou uma função que só existe em versão mais nova do WordPress.
Outros tipos e o que costumam significar na prática:
| Tipo de erro no log | Origem provável | Primeira ação |
|---|---|---|
Uncaught Error: Call to undefined function/method |
dependência ausente ou plugin desatualizado | desativar o plugin do caminho citado |
syntax error, unexpected ... |
código escrito para PHP mais novo que o do servidor | conferir versão de PHP exigida pelo plugin ou tema |
Allowed memory size of X bytes exhausted |
limite de memória do PHP | aumentar memory_limit e investigar o que consome |
Maximum execution time exceeded |
rotina longa (importação, cron, backup) | rodar via WP-CLI em vez de HTTP |
Cannot redeclare function ... |
plugin duplicado, ou pasta antiga copiada ao lado | remover a cópia duplicada |
Uncaught TypeError: ... must be of type |
incompatibilidade entre versões de plugin | rollback da versão recém atualizada |
Quando o caminho aponta para wp-content/themes/, o raciocínio é igual, mas a desativação é diferente: tema não se desativa, se substitui. Tenha um tema padrão instalado em todo site da carteira, justamente para isso.
Quando o caminho aponta para wp-includes/ ou wp-admin/, desconfie da versão do PHP. Core do WordPress raramente quebra sozinho. Um syntax error dentro de wp-includes/ depois de alguém mexer no seletor de versão do PHP no painel é caso clássico.
Desativar só o culpado, não o site inteiro
Com o slug em mãos, isole o mínimo necessário. Duas maneiras, ambas reversíveis.
Renomear a pasta funciona sempre, inclusive sem acesso ao painel, porque o WordPress simplesmente não encontra o arquivo principal e marca o plugin como inativo:
cd ~/public_html/wp-content/plugins
mv exemplo-slider exemplo-slider.off
Via WP-CLI é mais limpo, e a flag --skip-plugins permite rodar o comando mesmo com o site quebrado, porque o WP-CLI carrega o WordPress sem executar o código dos plugins:
wp plugin list --status=active --skip-plugins --skip-themes
wp plugin deactivate exemplo-slider --skip-plugins --skip-themes
Confirme o resultado por HTTP, não pelo navegador com cache:
curl -sI https://exemplo.com.br | head -n 1
# HTTP/2 200
Se voltou 200, você tem causa provável e site no ar. Só então tire o .off para reproduzir em ambiente separado e descobrir se o problema é o plugin, um conflito ou a versão do PHP. Não teste a hipótese no site do cliente que acabou de voltar.
A regra única para manter WP_DEBUG ligado em produção
Para não ficar com meia dúzia de critérios diferentes espalhados pela carteira, adote uma regra só e repita em todos os sites:
- Padrão:
WP_DEBUGeWP_DEBUG_LOGficam ligados apenas durante o diagnóstico. Resolvido o incidente, volte aowp-config.phpe desligue os dois. - Única exceção permitida: manter ligado de forma permanente só se as três condições valerem juntas:
WP_DEBUG_DISPLAYemfalse,WP_DEBUG_LOGapontando para um caminho absoluto fora da raiz pública, e truncamento periódico agendado do arquivo.
Sem essas três condições, debug ligado em produção enche o disco com debug.log, deixa o arquivo acessível pela web e, se alguém mexer no WP_DEBUG_DISPLAY depois, expõe caminho interno.
Log vazio também diz algo: o PHP não executou ou não conseguiu escrever
Log vazio é informação, não beco sem saída. Significa que o PHP não executou ou não conseguiu escrever.
.htaccessinválido. O Apache recusa a requisição antes do PHP. Renomeie o arquivo e teste. Se voltou, o conteúdo do.htaccessé o suspeito, e normalmente é uma linha colada de tutorial com diretiva não permitida no ambiente.- Permissão errada. Diretório com permissão que impede leitura, ou arquivo com permissão de escrita ampla demais que o servidor rejeita. A documentação do cPanel cita problema de permissão como um dos casos que aparecem na interface Errors, então vale voltar lá e ler com atenção.
- Limite de recurso atingido. Processo derrubado por limite de memória ou de entrada nem sempre deixa rastro no log do site. Sintoma comum: 500 ou 502 intermitente, que melhora sozinho e volta em horário de pico.
log_errorsdesligado. Se ninguém nunca configurou log naquele site, não existe log para ler. É exatamente o problema que o checklist da próxima seção resolve, e é o motivo pelo qual o primeiro incidente de um site novo custa mais caro que os seguintes.- Erro no navegador, não no servidor. Página que carrega o HTML e quebra depois é JavaScript. Log de PHP não vai mostrar nada. Console do navegador, sim.
Vale dizer o que normalmente não é: troca de plano. Fatal de PHP, .htaccess quebrado e conflito de plugin não melhoram com mais recurso. Se o log aponta um plugin, a correção é o plugin. Só faz sentido discutir recurso quando o log fala de memória, tempo de execução ou processos concorrentes, e mesmo aí a primeira pergunta é o que está consumindo.
Checklist para ter log de erro ligado antes do próximo incidente
Esse é o trabalho que transforma uma hora de investigação em cinco minutos de leitura. Faça uma vez por site, de preferência no onboarding.
- Confirmar que existe log gravável. Acesse uma URL do site, depois procure
error_logna raiz e emwp-content. Se não aparecer nada e o site tem erro conhecido, o log está desligado. - Garantir
display_errorsdesligado em produção. Nenhum visitante deve ver caminho de arquivo. Se o painel expõe a diretiva no seletor de opções do PHP, deixe emOff. - Deixar o bloco de debug pronto no
wp-config.php, comentado, comWP_DEBUG_LOGligado eWP_DEBUG_DISPLAYdesligado, conforme o snippet da seção 3. A regra é a mesma em todos os sites: liga no diagnóstico, desliga depois. Permanente só com as três condições da seção anterior (WP_DEBUG_DISPLAYemfalse, log fora da raiz pública e truncamento agendado). - Proteger o
debug.log. O padrão fica emwp-content/debug.log, que é acessível pela web em muitos setups. Defina um caminho fora da raiz pública comdefine( 'WP_DEBUG_LOG', '/home/usuario/logs/debug.log' );ou bloqueie o acesso ao arquivo. - Registrar onde ficam os logs de cada site numa planilha ou no gestor de senhas da agência: caminho do
error_log, caminho dodebug.log, versão do PHP, tema ativo. Em incidente, ninguém lembra. - Anotar a versão de PHP de cada site e revisar antes de atualizar plugin grande. Boa parte dos fatais de atualização é plugin novo em PHP antigo.
- Definir o tema de segurança. Um tema padrão instalado e atualizado em cada site, só para servir de fallback.
- Limpar log grande periodicamente.
error_logesquecido cresce até virar problema de disco. Truncar, não apagar durante incidente.
As diretivas envolvidas, para conferência rápida:
| Diretiva | Valor em produção | Efeito |
|---|---|---|
log_errors |
On |
grava erro em arquivo |
display_errors |
Off |
não mostra erro ao visitante |
WP_DEBUG |
true só durante diagnóstico (permanente só com as três condições da regra única) |
habilita o relatório de erros do WordPress |
WP_DEBUG_LOG |
caminho absoluto fora da raiz pública, ligado junto com WP_DEBUG |
grava em arquivo de log |
WP_DEBUG_DISPLAY |
false |
impede impressão na tela |
SCRIPT_DEBUG |
false |
evita carregar versões não minificadas |
O que dizer ao cliente enquanto o site volta
Cliente em pânico não quer stack trace. Quer três informações: o site voltou, qual foi a causa, e o que impede de repetir. Frase pronta, ajuste o nome:
O que essa frase tem: causa nomeada, hora do restabelecimento, escopo do que está fora, próximo passo com prazo. O que ela não tem: jargão, culpa difusa ("parece que o servidor deu uma instabilidade") e promessa que você não controla.
Se a causa não estiver confirmada, diga isso em vez de inventar. "O log aponta o plugin X como origem mais provável; isolei e o site voltou. Confirmo a causa no ambiente de teste ainda hoje." Cliente aceita hipótese declarada como hipótese. Não aceita descobrir depois que você chutou.
Depois do incidente, uma linha no histórico do site com data, sintoma, log lido, causa e ação. No terceiro incidente parecido, esse histórico é o que justifica propor staging, revisão de plugins ou plano de manutenção, com evidência em vez de opinião.
Referências
- Documentação oficial do cPanel — Errors. Consultado em 2026-09-16.