Log de erros no WordPress: como ativar, ler e desativar o debug com segurança

Quando um site WordPress quebra, a mensagem no navegador raramente mostra a causa completa. Você pode ver “houve um erro crítico neste site”, uma tela branca, um erro 500, uma página travada ou um comportamento estranho depois de atualizar plugin, tema ou versão do PHP.

Nessa situação, o log de erros WordPress ajuda a transformar um sintoma genérico em evidência técnica. Ele pode indicar qual arquivo falhou, qual plugin ou tema apareceu na mensagem, se houve erro fatal de PHP, limite de memória, timeout, função obsoleta ou falha de integração.

Mas debug também exige cuidado. Se for ativado sem critério, mensagens técnicas podem aparecer para visitantes. Se o arquivo debug.log ficar exposto, ele pode revelar caminhos internos do servidor, e-mails, tokens, dados de clientes e outras informações sensíveis.

Neste guia, você vai ver como ativar, ler e desativar o debug com segurança usando WP_DEBUG, WP_DEBUG_LOG e WP_DEBUG_DISPLAY=false.

Se o seu site mostra “houve um erro crítico neste site”, leia também o guia específico sobre erro crítico no WordPress. Se aparece “Internal Server Error”, veja o checklist de erro 500 no WordPress. Aqui o foco é coletar evidências no log antes de mexer demais.

Antes de qualquer alteração sensível: faça backup completo dos arquivos e do banco de dados. Se possível, teste em staging. Editar wp-config.php, alterar constantes de debug, consultar arquivos do servidor ou compartilhar logs exige cuidado, especialmente em lojas, áreas de membros, cursos, sites com formulários e ambientes de cliente.

O que é log de erros no WordPress?

Log de erros é um registro técnico do que aconteceu quando o site encontrou um problema. Em vez de mostrar apenas uma mensagem genérica no navegador, o log pode guardar detalhes que ajudam a descobrir a causa provável.

No WordPress, você pode encontrar diferentes tipos de log:

Tipo de log	Onde costuma ficar	Para que serve
debug.log do WordPress	Normalmente em wp-content/debug.log, quando ativado	Registrar erros, avisos e mensagens geradas durante a execução do WordPress, plugins e temas
Logs PHP da hospedagem	Painel da hospedagem, cPanel, Plesk, arquivo error_log ou suporte	Ver erros do PHP, limite de memória, timeout, permissões e falhas durante ou antes do carregamento
Logs do servidor	Apache, Nginx, LiteSpeed, PHP-FPM ou painel do provedor	Investigar erro 500, WAF, ModSecurity, status HTTP e falhas de infraestrutura
Logs de plugin	Área específica do plugin, como WooCommerce, gateway, formulário, segurança ou cache	Diagnosticar integrações, pagamentos, e-mails, APIs e tarefas internas

O ponto importante: nem todo erro aparece no mesmo lugar. Se o WordPress nem chegou a carregar, o debug.log pode não registrar nada. Nesses casos, os logs da hospedagem costumam ser mais úteis.

Quando vale ativar o WP_DEBUG no WordPress?

Ativar debug faz sentido quando você precisa de evidência técnica para diagnosticar um problema. Exemplos:

• o site mostra “houve um erro crítico neste site”;
• o navegador mostra erro 500 sem detalhes;
• uma página específica quebra depois de atualizar plugin ou tema;
• o painel abre, mas uma tela específica dá erro;
• uma requisição Ajax, cron, formulário, checkout ou integração falha sem mensagem clara;
• o suporte da hospedagem ou do plugin pediu o log;
• você precisa registrar o erro para enviar a um desenvolvedor.

Mesmo assim, trate como procedimento temporário. A documentação oficial do WordPress recomenda WP_DEBUG e as demais ferramentas de debug principalmente para instalações locais ou de staging, não como configuração permanente em sites publicados.

Quando não ativar debug diretamente em produção?

Evite ativar debug em produção sem plano quando:

• você não tem backup recente;
• não sabe acessar ou editar wp-config.php com segurança;
• o site tem alto tráfego e qualquer erro visível pode afetar usuários;
• há WooCommerce, membros, cursos, assinaturas ou dados sensíveis;
• você não sabe como desativar depois;
• o problema pode ser investigado antes em staging;
• a hospedagem já tem log de PHP disponível no painel;
• você pretende copiar e colar o log inteiro em fórum público.

Se o site é crítico, prefira criar ou usar um ambiente de staging WordPress e reproduzir o erro lá. Staging não substitui backup, mas reduz o risco de exibir mensagens técnicas no site real.

Pré-requisitos antes de editar o wp-config.php

O arquivo wp-config.php fica na raiz da instalação WordPress e contém configurações essenciais do site, incluindo dados de conexão com o banco. Um erro de sintaxe nele pode derrubar o site.

Antes de editar, confirme que você tem:

1. backup completo e restaurável de arquivos e banco de dados;
2. acesso ao painel da hospedagem, FTP/SFTP, gerenciador de arquivos ou SSH;
3. permissão para alterar o site, se for ambiente de cliente;
4. editor de texto confiável, que não quebre aspas, acentos ou codificação;
5. cópia do wp-config.php original antes da alteração;
6. horário de menor tráfego, se for site publicado;
7. plano de reversão: saber exatamente como desfazer a mudança;
8. cuidado para não compartilhar o conteúdo completo do arquivo, pois ele pode conter credenciais.

Se ainda não existe uma rotina confiável de cópia, veja o guia sobre backup WordPress em nuvem antes de prosseguir.

Como ativar log de erros WordPress com segurança

A configuração mais segura para diagnóstico pontual é ativar o debug e o log, mas desativar a exibição pública dos erros.

No wp-config.php, antes da linha:

/* That's all, stop editing! Happy blogging. */

adicione ou ajuste as constantes assim:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

O que cada linha faz:

• WP_DEBUG ativa o modo de debug do WordPress.
• WP_DEBUG_LOG grava mensagens no arquivo de log, normalmente wp-content/debug.log.
• WP_DEBUG_DISPLAY como false evita exibir mensagens de debug dentro das páginas.
• display_errors como 0 reforça que erros não devem aparecer para o visitante.

Atenção: use true e false sem aspas. A documentação oficial alerta que valores como 'false' entre aspas são strings, não booleanos, e podem ser interpretados como verdadeiro.

E se essas constantes já existem?

Não duplique constantes no wp-config.php. Primeiro procure se já existe algo como:

define( 'WP_DEBUG', false );

Se já existir, ajuste a linha existente temporariamente. Ter duas definições para a mesma constante pode gerar confusão, avisos ou fazer você acreditar que mudou uma configuração quando outra linha continua valendo.

Em algumas hospedagens gerenciadas, o provedor controla parte dessas configurações. Se a mudança não funcionar, consulte a documentação da hospedagem ou abra chamado com suporte.

Onde encontrar o debug.log WordPress?

Com WP_DEBUG_LOG ativado como true, o arquivo geralmente fica em:

wp-content/debug.log

Você pode acessá-lo pelo gerenciador de arquivos da hospedagem, FTP/SFTP ou SSH. Em alguns casos, ele só aparece depois que o erro acontece novamente. Por isso, após ativar o debug, reproduza o problema com cuidado: acesse a página que falha, salve a ação que gera erro ou rode o fluxo que costuma quebrar.

Se nada for gravado, possíveis explicações incluem:

• o erro acontece antes de o WordPress carregar;
• o site não tem permissão para criar ou escrever no arquivo;
• a hospedagem redireciona logs para outro local;
• o erro está em nível de servidor, PHP-FPM, WAF, Apache, Nginx ou LiteSpeed;
• a página problemática não foi acessada novamente depois da ativação;
• o cache ou CDN está servindo uma resposta antiga.

Nesses casos, procure logs no painel da hospedagem ou peça ao suporte registros do horário exato do problema.

Como ler o debug.log sem se perder

Um log pode parecer assustador, mas você não precisa entender tudo de uma vez. Comece pelo básico.

1. Procure data e horário do problema

Se o erro aconteceu às 14h30, procure entradas próximas desse horário. Atenção ao fuso horário do servidor: ele pode não ser o mesmo do Brasil.

2. Procure palavras de gravidade

Termos comuns:

• Fatal error: erro fatal que interrompeu a execução;
• Parse error: erro de sintaxe em código PHP;
• Warning: aviso importante, mas nem sempre derruba o site;
• Notice: aviso de menor gravidade, comum em código que precisa ajuste;
• Deprecated: função, argumento ou prática obsoleta;
• Uncaught Error ou Uncaught Exception: erro ou exceção não tratada;
• Allowed memory size exhausted: limite de memória atingido;
• Maximum execution time exceeded: tempo máximo de execução excedido.

Em site quebrado, dê prioridade a Fatal error, Parse error, Uncaught e mensagens ligadas ao horário exato do problema.

3. Identifique o caminho do arquivo

Uma mensagem pode citar algo como:

/wp-content/plugins/nome-do-plugin/arquivo.php

ou:

/wp-content/themes/nome-do-tema/functions.php

Isso não prova automaticamente que o plugin ou tema é o culpado absoluto, mas indica onde o erro apareceu. Às vezes um plugin apenas foi o primeiro a encontrar um problema causado por versão de PHP, dependência ausente, configuração do servidor ou conflito com outro plugin.

4. Veja se o erro é recorrente

Uma entrada isolada pode ser ruído. Muitas entradas repetidas no mesmo horário, com o mesmo arquivo e a mesma mensagem, merecem atenção.

5. Relacione com mudanças recentes

Pergunte:

• o erro começou depois de atualizar um plugin?
• a hospedagem mudou a versão do PHP?
• houve atualização do tema?
• alguém adicionou snippet em functions.php?
• cache, CDN ou firewall foram alterados?
• houve migração ou restauração recente?

Log bom é aquele que ajuda a montar uma linha do tempo.

Exemplos de mensagens e como interpretar

A tabela abaixo é apenas um guia inicial. A correção depende do contexto, da versão do WordPress, do plugin, do tema e da hospedagem.

Mensagem no log	O que pode indicar	Próximo passo seguro
Fatal error em pasta de plugin	Plugin pode ter conflito, bug ou incompatibilidade	Verificar atualização recente, documentação do plugin e testar desativação em staging ou com plano de reversão
Parse error em functions.php	Erro de sintaxe em código adicionado ao tema	Restaurar cópia anterior do arquivo ou remover o trecho recém-adicionado com backup
Allowed memory size exhausted	Limite de memória atingido	Conferir consumo, plugins pesados e limites da hospedagem; não apenas aumentar memória sem investigar causa
Maximum execution time exceeded	Processo demorou mais que o limite	Verificar importações, backups, plugins, consultas lentas ou tarefas agendadas
Deprecated	Código usa função, argumento ou prática antiga	Atualizar plugin/tema quando houver versão compatível; não tratar como emergência se o site funciona
Permission denied	Arquivo/pasta sem permissão adequada ou bloqueio do servidor	Acionar hospedagem; evitar permissões amplas às cegas
Erro em gateway, API ou webhook	Integração externa falhando	Conferir credenciais, ambiente sandbox/produção, status do serviço e logs do plugin

Não aplique correções perigosas só porque viu uma mensagem no log. O log aponta o local da investigação; ele não substitui diagnóstico.

O que nunca publicar em fóruns, comentários ou chats

Logs podem conter informações sensíveis. Antes de enviar para suporte, desenvolvedor ou fórum, revise e oculte dados como:

• caminho completo do servidor;
• nome de usuário da hospedagem;
• e-mails de administradores, clientes ou usuários;
• tokens, chaves de API, webhooks e senhas;
• dados de pedidos, CPF, telefone, endereço ou dados de pagamento;
• URLs privadas de staging, painel ou arquivos temporários;
• nomes de tabelas e prefixos do banco, quando não forem necessários;
• conteúdo completo do wp-config.php.

Prefira enviar apenas o trecho relevante: algumas linhas antes e depois da mensagem, com data/hora, URL afetada, o que você fez para reproduzir e quais mudanças recentes ocorreram.

Exemplo seguro de contextualização:

Horário aproximado: 2026-09-16, 14h30 BRT
URL afetada: /checkout/
Sintoma: erro 500 ao finalizar pedido
Mudança recente: atualização do plugin X pela manhã
Trecho do log: [removidos caminhos internos, e-mails e tokens]
Mensagem principal: Fatal error em /wp-content/plugins/plugin-x/...

Como desativar o debug depois do diagnóstico

Quando terminar de coletar o log, volte ao wp-config.php e desative o debug:

define( 'WP_DEBUG', false );
define( 'WP_DEBUG_LOG', false );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Se as linhas não existiam antes, você pode remover as constantes adicionadas ou deixá-las explicitamente como false, conforme o padrão de manutenção do site. O importante é não manter WP_DEBUG e WP_DEBUG_LOG ativos em produção sem necessidade.

Depois disso:

1. confirme que o site e o painel continuam carregando;
2. confira se erros não aparecem para visitantes;
3. remova o arquivo wp-content/debug.log se ele não for mais necessário;
4. se precisar guardar evidência, baixe uma cópia, oculte dados sensíveis e armazene em local seguro;
5. se o log precisar continuar existindo, fale com a hospedagem ou com um desenvolvedor para protegê-lo ou movê-lo para local não público.

Não confie apenas em “ninguém sabe a URL”. Arquivos dentro de diretórios públicos podem ser acessíveis dependendo da configuração do servidor.

Como proteger ou mover o debug.log?

A forma correta depende da hospedagem e do servidor. Apache, Nginx, LiteSpeed, hospedagem gerenciada e containers podem tratar regras de acesso de formas diferentes.

Caminhos possíveis, sempre com validação técnica:

• apagar o debug.log ao final do diagnóstico, se não houver necessidade de guardá-lo;
• armazenar uma cópia fora da pasta pública do site;
• configurar WP_DEBUG_LOG para um caminho de arquivo não público, quando permitido e testado no ambiente;
• pedir à hospedagem uma regra de bloqueio de acesso ao arquivo;
• usar ferramenta de log do provedor em vez de deixar arquivo em wp-content;
• aplicar regra específica no servidor apenas se você souber se o ambiente usa Apache, Nginx ou LiteSpeed.

Evite copiar regras de .htaccess ou Nginx aleatórias da internet sem saber se servem para seu ambiente. Uma regra errada pode derrubar imagens, downloads, painel, cache ou o site inteiro.

Logs da hospedagem: quando eles são melhores que o debug.log

O debug.log é útil, mas não cobre tudo. Acione ou consulte a hospedagem quando:

• o site mostra erro 500 antes de o WordPress carregar;
• o painel e o site público estão fora do ar;
• o log do WordPress fica vazio;
• há suspeita de limite de CPU, memória, processos, I/O ou banco;
• aparece Permission denied, timeout, bloqueio de firewall ou WAF;
• o erro acontece só em alguns horários;
• há falha depois de mudança de PHP, migração, SSL, cache de servidor ou CDN.

Ao abrir chamado, informe:

• URL afetada;
• horário aproximado com fuso;
• mensagem vista no navegador;
• ações recentes;
• trecho relevante do log, sem dados sensíveis;
• se o problema afeta site todo, painel, checkout ou página específica.

Um chamado com evidências tende a ser muito mais útil do que “meu WordPress está com erro”.

E o WP-CLI?

WP-CLI pode ajudar em diagnósticos quando você tem SSH e sabe em qual instalação está trabalhando. Ele pode listar plugins, versões e informações do ambiente, mas também pode executar ações que alteram arquivos e banco de dados.

Use WP-CLI com cautela. Para aprender o básico de segurança, veja o guia sobre como usar WP-CLI em hospedagem WordPress.

Neste artigo, a regra é simples: se você não tem certeza do comando, do diretório e do impacto, não rode em produção. Consulte documentação oficial, hospedagem ou desenvolvedor.

SAVEQUERIES e SCRIPT_DEBUG: preciso usar?

Na maioria dos casos, não.

SAVEQUERIES registra consultas ao banco de dados na variável global $wpdb->queries para análise técnica e pode impactar performance. Use apenas em diagnóstico controlado, de preferência em staging ou com orientação de desenvolvedor.

SCRIPT_DEBUG força o WordPress a carregar versões de desenvolvimento dos arquivos CSS e JavaScript do core. Ele é útil quando alguém está testando alterações nesses arquivos, mas raramente é necessário para diagnosticar erro crítico, erro 500 ou conflito comum de plugin.

Para a maioria dos leitores, o trio principal é:

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

com display_errors desligado e desativação assim que o diagnóstico terminar.

Checklist seguro para diagnosticar erro WordPress com log

Antes de ativar:

• [ ] Fiz backup completo de arquivos e banco.
• [ ] Sei restaurar ou tenho suporte para restaurar.
• [ ] Tenho acesso ao wp-config.php.
• [ ] Fiz cópia do wp-config.php original.
• [ ] Sei onde desfazer a alteração.
• [ ] Se possível, reproduzi o problema em staging.

Durante o diagnóstico:

• [ ] Ativei WP_DEBUG apenas temporariamente.
• [ ] Ativei WP_DEBUG_LOG para registrar em arquivo.
• [ ] Mantive WP_DEBUG_DISPLAY como false.
• [ ] Não deixei mensagens técnicas visíveis para visitantes.
• [ ] Reproduzi o erro com cuidado.
• [ ] Analisei horário, mensagem, arquivo e mudança recente.
• [ ] Não publiquei log completo em local público.

Depois do diagnóstico:

• [ ] Desativei WP_DEBUG.
• [ ] Desativei WP_DEBUG_LOG.
• [ ] Mantive WP_DEBUG_DISPLAY como false.
• [ ] Baixei ou salvei apenas o trecho necessário, com dados sensíveis ocultos.
• [ ] Apaguei, movi ou protegi o debug.log.
• [ ] Abri chamado ou enviei evidência filtrada para suporte/desenvolvedor.
• [ ] Registrei o que foi feito e o próximo passo.

Quando chamar um desenvolvedor ou a hospedagem?

Chame ajuda quando:

• o site está fora do ar e você não tem acesso seguro aos arquivos;
• o erro envolve WooCommerce, pedidos, pagamentos, membros ou dados recentes;
• o log mostra erro fatal em código customizado;
• o problema começou depois de atualização grande;
• há suspeita de invasão, malware ou alteração desconhecida de arquivos;
• o log aponta permissão, servidor, banco, WAF, PHP-FPM ou timeout;
• você não sabe editar wp-config.php sem risco;
• a solução exigiria mexer em banco, .htaccess, Nginx, permissões ou comandos SSH.

Não é fracasso chamar suporte. Em muitos casos, o melhor uso do log é justamente abrir um chamado mais objetivo.

Conclusão

Log de erros WordPress é uma ferramenta de diagnóstico. Ele ajuda a sair do “o site quebrou” para uma hipótese concreta: qual erro apareceu, em qual horário, em qual arquivo e depois de qual mudança.

Use com segurança: faça backup, prefira staging, ative WP_DEBUG_LOG, mantenha WP_DEBUG_DISPLAY=false, não exponha dados sensíveis e desligue tudo quando terminar.

O objetivo não é deixar o debug ligado para sempre. É coletar evidência suficiente para corrigir o problema certo, com menos tentativa e erro e menos risco para o site.