Ativar o WordPress Debug Log (modo Debug do WordPress)

Quando abres o teu site WordPress e vês uma página em branco ou um erro 500, o WordPress está a suprimir uma mensagem de erro que identificaria a causa imediatamente. Ativar o debug log do WordPress diz ao WordPress para escrever cada erro, aviso e notice de PHP num ficheiro — wp-content/debug.log — para que vejas exatamente qual o Plugin, Theme ou linha de código responsável.

TL;DR: Adiciona estas três constantes ao wp-config.php, mesmo acima da linha /* That's all, stop editing! Happy publishing. */ — define( 'WP_DEBUG', true );, define( 'WP_DEBUG_LOG', true ); e define( 'WP_DEBUG_DISPLAY', false );. Depois de guardares, recarrega a página e o WordPress escreve todos os erros PHP em wp-content/debug.log. Quando terminares a investigação, desativa o modo debug do WordPress antes de fazer push para produção.

Modo Debug do WordPress por ambiente de Hosting

A forma de aceder ao wp-config.php — e onde acaba por ficar o debug.log — depende do teu ambiente de Hosting. Usa a secção que corresponde à tua configuração.

Hosting partilhado (cPanel / FTP)

Em alojamentos partilhados como Bluehost, SiteGround ou Hostinger, o wp-config.php fica na raiz da tua instalação WordPress, normalmente em public_html/. Edita-o usando o File Manager do cPanel ou um cliente FTP como o FileZilla.

Problema comum de permissões: se o WordPress não consegue escrever o debug.log, a pasta wp-content/ precisa de ser gravável pelo servidor web. A permissão padrão é 755 para pastas. Não a definas para 777 num alojamento partilhado — isso torna a pasta gravável por toda a gente e é um risco de segurança.

Pela experiência do suporte do WP STAGING, o alojamento partilhado é onde o debug.log mais frequentemente falha em silêncio, porque muitos hosts partilhados capturam erros PHP no log do servidor em vez de deixar o WordPress criar o debug.log. Se o ficheiro nunca aparecer após ativares o WP_DEBUG, pergunta ao teu Hosting onde está guardado o log de erros PHP.

VPS / Servidor gerido (SSH)

Com acesso SSH, edita o wp-config.php diretamente a partir da linha de comandos:

nano /var/www/html/wp-config.php

Após guardar, segue o log em tempo real para ver os erros à medida que acontecem:

tail -f /var/www/html/wp-content/debug.log

Se o debug.log não for criado, verifica se a pasta wp-content/ pertence ao utilizador do servidor web (www-data em Ubuntu/Debian, apache ou nginx em CentOS/AlmaLinux):

ls -la /var/www/html/wp-content/
chown www-data:www-data /var/www/html/wp-content/

Desenvolvimento local (LocalWP / DevKinsta / XAMPP)

O debug.log aparece na mesma localização wp-content/debug.log, mas o caminho base depende do teu ambiente local:

• LocalWP: ~/Local Sites/<site-name>/app/public/wp-content/debug.log
• DevKinsta: ~/DevKinsta/projects/<site-name>/app/public/wp-content/debug.log
• XAMPP em Windows: C:xampphtdocs<site-name>wp-contentdebug.log

Ambientes locais raramente têm problemas de permissões porque o servidor web e a tua conta de utilizador correm como o mesmo processo. Se o debug.log nunca aparecer, confirma que o teu wp-config.php está na raiz do WordPress e não numa pasta acima.

Site de Staging WP STAGING

Nos nossos testes com o WP STAGING, ativar o modo debug no clone de Staging é a abordagem mais segura — o clone é uma cópia exata do site em produção, por isso qualquer erro que reproduzas vai corresponder ao ambiente de produção sem afetar visitantes reais.

Para ativar o modo debug no teu site de Staging, edita o wp-config.php dentro da pasta do Staging. O WP STAGING cria o site de Staging como uma subpasta ou subdomínio separado com o seu próprio wp-config.php, por isso as alterações aí não afetam a definição WP_DEBUG do site em produção.

Se não conseguires iniciar sessão no teu site de Staging, o debug log é o primeiro sítio onde verificar — falhas de login no Staging são, na maior parte das vezes, erros fatais PHP que só aparecem no log.

Como ativar o modo Debug do WordPress

Podes ativar o “modo debug” do WordPress editando algumas linhas no ficheiro wp-config.php da tua instalação WordPress:

1. Inicia sessão no cPanel ou liga-te ao teu site via FTP
2. Usa o File Manager do cPanel ou o teu cliente FTP e edita o ficheiro wp-config.php
3. Copia as linhas abaixo para o ficheiro wp-config.php; se já existirem, altera os valores para true:

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

Atenção: garante que copias as linhas exatamente como mostradas e não te esqueças de um ponto e vírgula ou outros caracteres!

1. Cola as linhas copiadas mesmo acima da linha que diz
   /* That's all, stop editing! Happy publishing. */

Após recarregar o site, o WordPress vai escrever todos os erros PHP no ficheiro debug.log.
O WordPress guarda esse ficheiro na pasta: wp-content/debug.log

Mostrar erros no frontend WordPress

Se quiseres ver os erros do debug log diretamente no ecrã em vez de ativar o ficheiro debug.log, altera a linha que diz define( 'WP_DEBUG_DISPLAY', false );

Renomeia para: define( 'WP_DEBUG_DISPLAY', true );.

O WordPress não cria o ficheiro debug.log

Alguns fornecedores de Hosting[1] não permitem a criação do debug.log do WordPress. Eles capturam todos os erros PHP e deixam o WordPress escrevê-los num ficheiro de log separado.

Se o WordPress não consegue criar o debug.log, segue esta árvore de decisão para encontrar a causa:

1. Procura um ficheiro de log alternativo. Verifica a raiz do site por um ficheiro chamado error_log, ou procura uma pasta /logs/. Muitos alojamentos partilhados, incluindo o HostGator, redirecionam os erros PHP para o log do servidor em vez de permitirem que o WordPress escreva o debug.log. Se não encontrares ficheiros de log, pergunta ao teu fornecedor de Hosting onde guardam os logs de erros PHP.

2. Verifica as permissões da pasta. A wp-content/ tem de ser gravável pelo servidor web. Num servidor com acesso SSH, executa:

ls -la /path/to/wp-content/

A pasta deve ser propriedade de www-data (Ubuntu/Debian) ou apache (CentOS). A permissão padrão é 755. Se a pasta for propriedade de root e o utilizador do servidor web não puder escrever nela, o debug.log falha em silêncio.

3. Verifica se display_errors está a sobrepor-se às tuas definições. Algumas configurações php.ini do servidor ou diretivas .htaccess definem php_flag display_errors Off, o que pode suprimir o output mesmo quando o WP_DEBUG_DISPLAY está em true. Verifica as definições PHP no painel de controlo do teu Hosting ou pergunta ao teu host.

4. Verifica se um must-use plugin está a suprimir erros. Ficheiros em wp-content/mu-plugins/ carregam antes de tudo o resto e podem sobrepor-se aos handlers de erros do WordPress. Se o teu host instalou um must-use plugin que interceta erros, pode impedir o debug.log de ser escrito. Inspeciona quaisquer ficheiros em wp-content/mu-plugins/ se essa pasta existir.

5. Verifica o nível de error_reporting. Se o error_reporting estiver demasiado restritivo — por exemplo, só E_ERROR — o PHP não vai registar avisos e notices. O WordPress define error_reporting(E_ALL) quando WP_DEBUG está em true, mas um Plugin ou configuração do servidor pode alterar isto depois de o WordPress carregar. Consulta a documentação do PHP error_reporting para a lista completa de constantes e o que cada nível cobre.

6. Verifica se a pasta do caminho do log existe. Se já definiste o WP_DEBUG_LOG para um caminho personalizado, confirma que a pasta nesse caminho existe e é gravável pelo servidor web.

Em alternativa, podes usar o método acima e alterar
define( 'WP_DEBUG_DISPLAY', false ); para
define( 'WP_DEBUG_DISPLAY', true );

Se isto funcionar, vais ver os erros relevantes no frontend. Isso vai ajudar-te a resolver o erro fatal.

Podes encontrar instruções mais detalhadas sobre como ativar o modo debug do WordPress na documentação de Debugging do WordPress.

À data da escrita deste artigo: [1] HostGator

Método alternativo para debugar erros fatais quando o debug.log não é gerado

Às vezes, quando ativas o modo WP_DEBUG para resolver um erro fatal, podes verificar que o teu fornecedor de Hosting impede a criação do ficheiro debug.log. Mesmo definir WP_DEBUG_DISPLAY para true nem sempre ajuda a mostrar o erro no frontend.

Se estás preso nesta situação, aqui está uma solução que funciona quando nada mais funciona.

Forçar a apresentação de erros no wp-config.php

Este snippet força o erro fatal a ser mostrado:

register_shutdown_function(function () {
    $error = error_get_last();
    if ($error) {
        print_r($error);
    }
});

🚨 Lembra-te de remover o snippet após o debug e usa apenas quando tens acesso FTP para uma reversão segura.

Ler o WordPress Debug Log

Quando o debug.log existir, abre-o em qualquer editor de texto. Cada linha segue este padrão:

[DD-Mon-YYYY HH:MM:SS UTC] PHP Fatal error: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Warning: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: <message> in /path/to/file.php on line N

Eis o que cada classe de erro significa e quando agir:

PHP Fatal error — o PHP parou de executar. Esta é sempre a causa de uma página em branco ou erro 500. O caminho do ficheiro e o número da linha na entrada do log indicam-te exatamente onde procurar. Encontra o Plugin ou Theme cujo ficheiro é mencionado na entrada e desativa-o para confirmar.

PHP Warning — o PHP deparou-se com algo inesperado, mas continuou a correr. Os avisos não causam páginas em branco por si só, mas frequentemente indicam um bug que se tornará um erro fatal noutras condições. Se estás a ativar o debug log do WordPress para identificar avisos PHP relacionados com limites de configuração PHP, um aviso de max_input_vars de um Plugin com muitos formulários é uma entrada comum.

PHP Notice — o PHP notou um potencial problema, como uma variável indefinida. As notices raramente indicam um bug real em produção, mas se o mesmo notice aparecer milhares de vezes por carregamento de página, pode sinalizar um loop ou problema de recursão que degrada o desempenho.

Erros de base de dados $wpdb — linhas que começam por WordPress database error indicam que uma query falhou. Normalmente apontam para um Plugin que está a gerar uma query SQL mal-formada ou para um problema nas tabelas da base de dados WordPress que a query usa. A mensagem de erro inclui a query que falhou, o que torna o Plugin culpado fácil de identificar.

Quando encontrares um erro fatal ou um aviso repetido, olha para o caminho do ficheiro na entrada do log. Se pertencer a um Plugin ou Theme, desativa-o, recarrega a página e confirma que as entradas do log param.

Se o debug log mostrar erros da REST API do WordPress, a entrada do log normalmente refere a função exata que falhou — segue o guia dedicado a partir desse ponto de partida. Se mostrar erros ERR_CONNECTION_REFUSED, estes têm origem na camada de servidor ou de rede, e não no PHP. Para erros 414 Request-URI Too Large, o log normalmente identifica qual o Plugin que está a gerar o URL excessivamente grande.

Alterar a localização do debug.log

Podes alterar o caminho que o WordPress usa para registar erros mudando o valor da constante WP_DEBUG_LOG.

Abre o wp-config.php e procura a linha que contém WP_DEBUG_LOG.

Procura: define( 'WP_DEBUG_LOG', true );

Renomeia para: define( 'WP_DEBUG_LOG', '/logs/errors.log' );

Isto permite ao WordPress escrever mensagens de erro para um caminho de ficheiro diferente.

Como caminho de destino também podes usar /dev/stderr ou /dev/stdout. Isto é útil em Docker ou outros ambientes em contentores onde queres todos os logs num stream de output partilhado.

Desativar o modo Debug no WordPress após a resolução de problemas

Assim que terminares a investigação, desativa o modo debug imediatamente. O ficheiro debug.log é acessível pela web por defeito em wp-content/debug.log e pode conter detalhes de erros da base de dados, caminhos de ficheiros e outras informações do servidor que não devem ser publicamente legíveis.

Elimina o ficheiro debug.log e desativa o registo de erros voltando a definir define( 'WP_DEBUG', true ); para define( 'WP_DEBUG', false );.

Desativa sempre o modo debug WordPress antes de fazer push para produção quando trabalhas num site de Staging. O fluxo de push do WP STAGING é o checkpoint certo para confirmar que o WP_DEBUG está desativado antes do clone sobrescrever o site em produção.

Artigos relacionados

• Página em branco num site de Staging WordPress
• Como corrigir um erro 500 e página em branco WordPress
• Como fazer debug de erros JavaScript na consola do navegador