# 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.

> 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.

João Rizzon · 2026-09-15 · Painéis

---

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](https://docs.cpanel.net/cpanel/metrics/errors/), 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_errors` e `error_log`). Em muitos ambientes de hospedagem compartilhada, o PHP escreve num arquivo `error_log` dentro 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:

```bash
# 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! */`:

```php
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:

```bash
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 function` normalmente é 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:

```bash
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:

```bash
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:

```bash
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_DEBUG` e `WP_DEBUG_LOG` ficam ligados apenas durante o diagnóstico. Resolvido o incidente, volte ao `wp-config.php` e desligue os dois.
- **Única exceção permitida:** manter ligado de forma permanente só se as três condições valerem juntas: `WP_DEBUG_DISPLAY` em `false`, `WP_DEBUG_LOG` apontando 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.

- **`.htaccess` invá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_errors` desligado.** 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_log` na raiz e em `wp-content`. Se não aparecer nada e o site tem erro conhecido, o log está desligado.
- **Garantir `display_errors` desligado 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 em `Off`.
- **Deixar o bloco de debug pronto no `wp-config.php`, comentado**, com `WP_DEBUG_LOG` ligado e `WP_DEBUG_DISPLAY` desligado, 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_DISPLAY` em `false`, log fora da raiz pública e truncamento agendado).
- **Proteger o `debug.log`.** O padrão fica em `wp-content/debug.log`, que é acessível pela web em muitos setups. Defina um caminho fora da raiz pública com `define( '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 do `debug.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_log` esquecido 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 site parou por causa de uma atualização do plugin X, que gerou um erro fatal de PHP. Já isolei o plugin e o site voltou ao ar às 14h35. A funcionalidade dele está temporariamente desativada. Vou testar a atualização em ambiente separado e reativar quando estiver estável, com previsão para amanhã."

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.

