Logs de erro do WordPress: como achar a causa do problema

Por que você precisa dos logs de erro do WordPress

Quando um site apresenta tela branca, erro 500 ou lentidão, a primeira reação é testar plugins e temas às cegas. Isso pode levar horas e, pior, derrubar o site de vez. Os logs de erro do WordPress registram exatamente o que aconteceu antes do problema: qual arquivo gerou o erro, em qual linha e qual foi a mensagem. Com eles, o diagnóstico deixa de ser tentativa e erro e vira leitura de dados.

Para quem gerencia vários sites, a importância é ainda maior. Cada minuto de inatividade em um site cliente significa prejuízo e retrabalho. Centralizar a leitura dos logs permite identificar erros recorrentes antes que se tornem críticos. Este artigo mostra o caminho completo: ativar, localizar, interpretar e, principalmente, agir com base nos registros.

O que são os logs de erro do WordPress

O WordPress, por padrão, esconde os erros do visitante, mas pode registrá-los em um arquivo de log. Esse registro é o debug.log, criado na pasta wp-content. Ele armazena avisos, erros fatais e notificações de PHP, com data, hora e o caminho do arquivo responsável.

Existem três níveis principais de mensagens:

• Notice (aviso): algo não crítico, mas que indica má prática. Ex.: variável não definida.
• Warning (alerta): um problema potencial, como uso de função obsoleta.
• Fatal error (erro fatal): interrompe a execução do PHP. É o que causa tela branca ou erro 500.

Além do debug.log, a hospedagem pode ter seus próprios logs de erro (error_log), geralmente na raiz do site. Eles capturam erros antes mesmo do WordPress carregar. Saber a diferença ajuda a escolher onde procurar.

Como ativar os logs de erro no WordPress

Para ativar o log, você precisa editar o arquivo wp-config.php, localizado na raiz do site. Antes de qualquer alteração, faça um backup do arquivo. Você pode editar via FTP, gerenciador de arquivos do painel da hospedagem ou SSH.

Passo a passo para ativar o debug

1. Acesse o arquivo wp-config.php.
2. Procure a linha que contém WP_DEBUG. Se não existir, adicione antes do comentário final /* That's all, stop editing! */.
3. Adicione ou altere as seguintes constantes:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

• WP_DEBUG ativa o modo de depuração.
• WP_DEBUG_LOG faz com que os erros sejam salvos em wp-content/debug.log.
• WP_DEBUG_DISPLAY controla a exibição na tela. Recomenda-se false para não expor informações a visitantes.

Salve o arquivo. O log será criado automaticamente quando ocorrer o primeiro erro. Se o arquivo não aparecer, verifique as permissões da pasta wp-content: ela precisa permitir escrita.

Importante: após o diagnóstico, remova ou comente as linhas, ou defina WP_DEBUG como false. Deixar o debug ativo em produção consome recursos e pode expor dados sensíveis.

Ativando via wp-cli

Se você tem acesso SSH e WP-CLI instalado, pode ativar o debug com um comando:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

Isso é útil para quem gerencia muitos sites e quer automatizar o processo.

Onde encontrar os logs de erro

Depois de ativar, o arquivo debug.log fica em wp-content/debug.log. Você pode baixá-lo via FTP ou visualizá-lo pelo gerenciador de arquivos da hospedagem. Se o site estiver fora do ar, use o FTP ou o painel da hospedagem para acessar os arquivos.

Além do debug.log, verifique o error_log na raiz do site. Muitas hospedagens também oferecem logs de erro no cPanel ou Plesk, na seção “Logs” ou “Métricas”.

Como interpretar as mensagens

Um log típico tem o seguinte formato:

[12-Mar-2025 14:32:10 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function my_custom_function() in /home/meu-site/wp-content/themes/meu-tema/functions.php:15

Vamos decompor:

• Data e hora: ajuda a correlacionar com o momento do problema.
• Tipo de erro: Fatal error, Warning, Notice.
• Mensagem: descreve o que aconteceu. No exemplo, função indefinida.
• Arquivo e linha: mostra exatamente onde o erro ocorreu.

Com essas informações, você sabe qual plugin ou tema está causando o problema. Se o erro vier de um plugin, a solução costuma ser atualizar, reconfigurar ou substituir o plugin. Se for do tema, verifique se há conflito com o WordPress ou com plugins.

Erros comuns que os logs revelam

Alguns erros aparecem com frequência nos logs de sites WordPress. Conhecê-los acelera o diagnóstico.

Mensagem	Significado	Ação típica
PHP Fatal error: Out of memory	Limite de memória do PHP foi excedido.	Aumente o memory_limit no php.ini ou no wp-config.
PHP Warning: File is not a valid image	Upload de imagem corrompida ou tipo não permitido.	Verifique o arquivo e as configurações de upload.
PHP Notice: Undefined index	Variável não definida, geralmente em formulários.	Corrija o código do plugin ou tema.
PHP Fatal error: Call to undefined function	Função de um plugin ou tema que não está ativo.	Ative o plugin ou remova a chamada.

Erros de memória são comuns em sites com muitos plugins. Aumentar o limite para 256M costuma resolver, mas o ideal é otimizar o site. Veja nosso guia sobre erro 500 no WordPress para mais detalhes.

Como usar os logs para diagnosticar problemas específicos

Erro 500 e tela branca

Quando o site retorna erro 500 ou tela branca, o log costuma mostrar um fatal error. Se o erro for de um plugin, desative-o via FTP ou painel. Se for do tema, ative um tema padrão (como Twenty Twenty-Four). O log indica exatamente qual arquivo está causando o problema, então você não precisa testar um por um.

Lentidão e erros intermitentes

Lentidão pode ter várias causas, e os logs ajudam a identificar erros que ocorrem em segundo plano, como chamadas a APIs externas que falham. Acompanhe o log durante um período para ver padrões. Se houver muitos warnings, isso pode sobrecarregar o servidor.

Erros no WooCommerce

Lojas têm erros específicos, como falhas no processamento de pagamento. Os logs do WooCommerce ficam em wp-content/uploads/wc-logs/. Eles são essenciais para diagnosticar problemas de checkout. Veja nosso artigo sobre checkout do WooCommerce travando.

Quando NÃO usar logs de erro

Os logs mostram o que aconteceu, mas nem sempre revelam a causa raiz de problemas de configuração ou de rede. Por exemplo, se o site está lento por causa de um servidor sobrecarregado, o log do WordPress pode não mostrar nada relevante. Nesse caso, verifique os logs do servidor (Apache, Nginx) e métricas de performance.

Além disso, erros de cache ou de DNS não aparecem nos logs do WordPress. Para questões de SSL ou mixed content, use ferramentas específicas.

Erros comuns ao ativar o debug

Ativar o debug parece simples, mas alguns erros podem acontecer:

• Erro de sintaxe no wp-config: se você adicionar as constantes no lugar errado, o site pode quebrar. Sempre edite com cuidado e mantenha um backup.
• Log não é criado: verifique as permissões da pasta wp-content. Ela precisa ter permissão de escrita (geralmente 755 ou 775).
• Erros exibidos na tela: se WP_DEBUG_DISPLAY estiver como true, os erros aparecem para os visitantes. Mantenha-o como false em produção.

Se o site quebrar após editar o wp-config, restaure o backup ou remova as linhas adicionadas via FTP.

Prevenção: monitorando logs em vários sites

Para quem administra vários sites, verificar logs manualmente é inviável. Ferramentas de monitoramento podem coletar e analisar logs automaticamente. O painel 100% WP centraliza a gestão de múltiplos sites, incluindo a verificação de erros e a aplicação de atualizações. Com ele, você recebe alertas quando um site apresenta erros críticos, permitindo agir antes que o cliente perceba.

Além disso, adote boas práticas:

• Atualize plugins e temas regularmente, como explicamos em atualizações contínuas.
• Use um ambiente de staging para testar mudanças antes de ir para produção.
• Programe verificações periódicas dos logs, mesmo que não haja erros aparentes.

Quando chamar um profissional

Se os logs indicam um erro complexo, como conflito entre plugins ou um hack, talvez seja hora de chamar um especialista. Se o site foi comprometido, os logs podem mostrar atividades suspeitas, mas a limpeza exige conhecimento avançado. Nossa equipe oferece correção de erros pós-atualização e pode ajudar a resolver problemas que você não consegue solucionar sozinho.

Em resumo, os logs de erro do WordPress são a ferramenta mais confiável para diagnosticar problemas. Ativá-los é rápido e pode salvar horas de trabalho. Incorpore a leitura de logs à sua rotina de manutenção e evite dores de cabeça.

Fonte: Documentação oficial do WordPress