Ativar WP_DEBUG no WordPress: como ligar o debug

Tipo Erro de PHP

Nome do erro Como ativar o modo de depuração (WP_DEBUG)

Severidade Informativo

Descrição O WP_DEBUG é a constante do WordPress que liga o modo de depuração e faz o PHP exibir ou registrar os erros, avisos e notices que normalmente ficam escondidos. Ativá-lo é o primeiro passo para diagnosticar tela branca, erro fatal e conflitos de plugin, porque revela o arquivo e a linha exatos da falha.

O que é o modo de depuração WP_DEBUG?

Ativar o debug no WordPress (a constante WP_DEBUG) significa ligar o modo de depuração definindo constantes no wp-config.php. Por padrão, o WordPress esconde os erros de PHP em produção por segurança, o que faz problemas aparecerem como tela branca, sem pista nenhuma. Com o WP_DEBUG ligado (e o WP_DEBUG_LOG), todo erro, aviso (warning) e notice passa a ser registrado em um arquivo de log, sem precisar ser mostrado ao visitante.

Como identificar

O site mostra tela branca ou “There has been a critical error” sem dizer qual arquivo falhou.
Você precisa achar qual plugin ou tema está causando um erro fatal e não há mensagem visível.
Aparecem avisos de “Deprecated” ou “Undefined array key” intermitentes que você quer registrar.
Um desenvolvedor pediu o conteúdo do wp-content/debug.log e o arquivo ainda não existe.

Antes de começar: Faça backup do wp-config.php antes de editá-lo. Nunca deixe WP_DEBUG_DISPLAY como true em produção: ele expõe caminhos de arquivo e detalhes do servidor a qualquer visitante. Apague o wp-content/debug.log depois, porque ele fica acessível e pode revelar informações sensíveis.

Como prevenir

Use sempre WP_DEBUG_LOG com WP_DEBUG_DISPLAY false em produção, para depurar sem expor o site
Desligue o WP_DEBUG e apague o debug.log assim que terminar o diagnóstico
Em ambiente de staging, mantenha o debug ligado para flagrar avisos antes de subir para produção

Erros relacionados

Causa

WP_DEBUG vem definido como false no wp-config.php padrão de produção, escondendo os erros
WP_DEBUG_LOG não está ativo, então nada é gravado em wp-content/debug.log
WP_DEBUG_DISPLAY ligado em produção exibiria o erro ao visitante, então é deixado desligado e o erro some da vista
A constante foi colocada depois da linha 'That's all, stop editing!', onde o WordPress já ignora
Um plugin de cache ou de segurança sobrescreve as constantes de debug

Como resolver

Abra o wp-config.php via FTP: conecte-se por FTP ou pelo gerenciador de arquivos da hospedagem e edite o wp-config.php na raiz do site.
Ative o debug com log e sem exibir na tela: adicione as constantes ANTES da linha 'That's all, stop editing!'. Em produção, mantenha o DISPLAY como false para o erro ir só para o log:
```
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);
```
Reproduza o problema: abra a página ou execute a ação que gerava o erro. O WordPress grava a falha no log nesse momento.
Leia o wp-content/debug.log: abra o arquivo wp-content/debug.log via FTP. A última entrada de 'Fatal error' aponta o arquivo e a linha do problema.
Desligue o debug ao terminar: volte WP_DEBUG para false e apague o debug.log. Deixar o debug ligado em produção pode vazar caminhos do servidor para quem não deveria ver.

PHP

// wp-config.php — modo de depuracao seguro (antes de "That's all, stop editing!")
define( 'WP_DEBUG', true );           // liga o modo de depuracao
define( 'WP_DEBUG_LOG', true );       // grava em wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false );  // NAO mostra o erro ao visitante
@ini_set( 'display_errors', 0 );      // reforca: nada na tela em producao

Perguntas frequentes

Ativar o WP_DEBUG deixa o site mais lento ou inseguro?

Ligado com WP_DEBUG_DISPLAY false, o impacto é mínimo e nada aparece ao visitante. O risco está em deixar o DISPLAY como true em produção, que expõe caminhos do servidor, ou em esquecer o debug.log acessível.

Onde fica o arquivo debug.log?

Em wp-content/debug.log, criado automaticamente quando WP_DEBUG_LOG está ativo e ocorre o primeiro erro. Se o arquivo não existe, ou o debug não está ligado ou nenhum erro foi registrado ainda.

Liguei o WP_DEBUG mas nada acontece. Por quê?

Verifique se as constantes estão antes da linha 'That's all, stop editing!' no wp-config.php; depois dela o WordPress ignora. Confira também se um plugin de cache ou segurança não está sobrescrevendo as constantes.

Qual a diferença entre WP_DEBUG_LOG e WP_DEBUG_DISPLAY?

O WP_DEBUG_LOG grava os erros em um arquivo de log. O WP_DEBUG_DISPLAY decide se os erros aparecem na tela. Em produção a regra é LOG true e DISPLAY false: você lê o log e o visitante não vê nada.

Posso ativar o debug sem mexer no wp-config.php?

Sim, alguns plugins de debug ligam o WP_DEBUG por uma tela do painel. Mas se o site está com tela branca e o wp-admin não abre, a edição via FTP do wp-config.php é o caminho mais direto.

Preciso desligar o WP_DEBUG depois de resolver?

Sim. Volte WP_DEBUG para false e apague o debug.log ao terminar. Manter o debug ligado em produção acumula um log grande e pode expor informações do servidor a quem acessar o arquivo.

Pro Grave

Como corrigir Failed opening required no WordPress

O Failed opening required é um erro fatal de PHP que aparece quando o código manda incluir um arquivo (com require) que não existe no caminho informado, está com permissão negada ou foi apagado. O WordPress para na hora e a página não abre, geralmente após uma migração, uma atualização interrompida ou um plugin removido pela metade.

Crítico

Como corrigir Parse error / syntax error no PHP

O parse error (syntax error) é um erro fatal de PHP que aparece quando há um erro de digitação no código, como uma chave, ponto e vírgula ou parêntese faltando. No WordPress, ele costuma surgir logo após editar o functions.php ou colar um snippet, e derruba a página exata onde o PHP não consegue interpretar o código.

Pro Grave

Como corrigir a incompatibilidade do Tutor LMS com PHP 8.3

A incompatibilidade do Tutor LMS com PHP 8.3 acontece quando uma versão do plugin escrita para PHP 7.4 roda num servidor já no PHP 8.3, gerando avisos de Deprecated e, em alguns casos, erro fatal ao salvar cursos ou abrir o construtor de quiz. A documentação oficial homologa o plugin a partir do PHP 7.4.

Pro Grave

Como corrigir a incompatibilidade do Astra Pro com PHP 8.3

O erro de compatibilidade do Astra Pro com o PHP 8.3 acontece quando uma versão antiga do addon roda num servidor já no PHP 8.3, disparando avisos de deprecated ou um fatal error que derruba o front-end ou o Personalizar. A correção é alinhar tema, plugin Astra Pro e licença na versão mais recente.

Pro Atenção

Como corrigir avisos de Deprecated no PHP 8 do WordPress

Os avisos de Deprecated no PHP 8 aparecem quando um plugin ou tema usa um recurso da linguagem que ainda funciona, mas foi marcado para remoção em versões futuras. Não derrubam o site, mas poluem a tela e os logs e indicam código desatualizado que pode quebrar de vez em um PHP mais novo.

Pro Grave

Como corrigir Cannot redeclare function

O erro Cannot redeclare function é um erro fatal de PHP que ocorre quando a mesma função é definida duas vezes na execução. No WordPress, costuma surgir ao colar um snippet repetido no functions.php ou ao ativar dois plugins que declaram uma função com o mesmo nome.

Setores

Extensões

Integrações

Como ativar o modo de depuração (WP_DEBUG)

O que é o modo de depuração WP_DEBUG?

Como identificar

Como prevenir

Erros relacionados

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir Failed opening required no WordPress

Como corrigir Parse error / syntax error no PHP

Como corrigir a incompatibilidade do Tutor LMS com PHP 8.3

Como corrigir a incompatibilidade do Astra Pro com PHP 8.3

Como corrigir avisos de Deprecated no PHP 8 do WordPress

Como corrigir Cannot redeclare function

Setores

Extensões

Integrações

Extensões

Hero Sections

Seções de CTA

Login

Blog

Cabeçalhos

Seções de FAQ

Cadastro

Blog individual

Rodapés

Seções de contato

Seções de preços

Faixas

Portfólio

Seções de equipe

Números

Logotipos