Como depurar erros de banco de dados no WordPress usando o debug.log

Erros de banco de dados no WordPress estão entre as causas mais frequentes de falhas como a “Tela Branca da Morte” (WSOD), erros 500 e problemas intermitentes de conexão. Muitas vezes, a mensagem na tela do usuário é genérica demais para um diagnóstico preciso. É nesse cenário que o debug.log nativo do WordPress se torna a ferramenta essencial.

Ativando o debug.log no WordPress

A depuração via log é controlada por constantes definidas no arquivo wp-config.php, localizado na raiz da instalação. Para ativá-la, adicione ou altere as seguintes linhas, de preferência antes do comentário /* Isto é tudo, pode parar de editar! */:

// Ativar o modo debug
define( 'WP_DEBUG', true );

// Salvar erros em um arquivo
define( 'WP_DEBUG_LOG', true );

// Não exibir erros na tela
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Após salvar o arquivo, o WordPress começará a registrar todos os erros, avisos e notificações no arquivo /wp-content/debug.log. Você pode acessá-lo via FTP, pelo gerenciador de arquivos do painel de hospedagem ou, se tiver acesso SSH, com o comando tail -f /caminho/wp-content/debug.log para acompanhar os erros em tempo real.

Interpretando o formato do debug.log

Um registro típico de erro de banco de dados segue este padrão:

[23-Jul-2026 10:32:11 UTC] WordPress database error Table 'meubanco.wp_options' doesn't exist for query 
SELECT option_value FROM wp_options WHERE option_name = 'siteurl' LIMIT 1 
made by require('wp-blog-header.php'), require_once('wp-load.php'), 
require_once('wp-config.php'), require_once('wp-settings.php'), 
wp_not_installed, get_option

Cada entrada contém quatro partes essenciais para o diagnóstico:

• Data e hora – O momento exato em que o erro ocorreu, em UTC.
• Tipo do erro – A string “WordPress database error” indica que a consulta SQL falhou.
• Mensagem – A descrição do problema, como “Table doesn’t exist” ou “Unknown column”.
• Stack trace – A sequência de chamadas de função que levou ao erro. É a parte mais valiosa, pois revela qual plugin ou tema disparou a consulta problemática.

Erros de banco de dados comuns e como resolvê-los

1. Table ‘database.wp_xxx’ doesn’t exist

Causa: Uma tabela que o WordPress ou um plugin espera encontrar está ausente. Pode ocorrer após uma restauração de backup incompleta, falha na desinstalação de um plugin ou corrupção de tabelas.

Solução:

• Verifique se a constante $table_prefix no wp-config.php corresponde ao prefixo real das tabelas no banco.
• Use o phpMyAdmin ou um plugin como WP phpMyAdmin para confirmar se a tabela existe.
• Se a tabela pertencia a um plugin, reinstale o plugin ou restaure a tabela a partir de um backup recente.

2. Unknown column ‘column_name’ in ‘field list’

Causa: Uma coluna necessária não foi encontrada na tabela. Situação típica após uma atualização de plugin ou tema que adicionou novos campos, mas o script de upgrade não foi executado completamente.

Solução: Desative e reative o plugin problemático para forçar a execução do script de instalação. Alternativamente, acesse https://seusite.com/wp-admin/upgrade.php para rodar a atualização do banco de dados do WordPress.

3. Can’t connect to MySQL server

Causa: Credenciais de banco incorretas, servidor MySQL fora do ar ou limite de conexões simultâneas atingido. Este erro geralmente aparece como “Error establishing a database connection” no front-end.

Solução: Confira as constantes DB_HOST, DB_NAME, DB_USER e DB_PASSWORD no wp-config.php. Confirme com sua hospedagem se o serviço MySQL está operacional e se o seu plano não atingiu o limite de conexões.

4. Deadlock found when trying to get lock

Causa: Duas ou mais transações concorrentes tentam modificar os mesmos registros em ordens diferentes. É mais comum em sites de alto tráfego ou em funcionalidades de e-commerce que atualizam estoque simultaneamente.

Solução: Para sites menores, reiniciar o MySQL costuma resolver o conflito momentâneo. A solução definitiva envolve otimizar as consultas ou implementar um sistema de filas para operações de escrita. Também vale revisar se algum plugin recente introduziu transações longas e desnecessárias.

Ferramentas para facilitar a leitura do debug.log

Embora o arquivo de texto seja perfeitamente legível, algumas ferramentas tornam a análise mais produtiva:

• Query Monitor – Exibe todos os erros de banco de dados diretamente na barra de administração do WordPress, com detalhes completos da consulta e do stack trace.
• Log Viewer (plugin) – Permite visualizar e filtrar o debug.log dentro do próprio painel administrativo.
• Terminal SSH – Com o comando tail -f /caminho/wp-content/debug.log, você monitora os erros em tempo real enquanto navega pelo site.

Quando o erro não aparece no debug.log

Há ocasiões em que o problema é tão severo que o WordPress não consegue nem mesmo registrar o erro no arquivo de log. Nesses casos, outras abordagens são necessárias:

• Logs do servidor: Consulte o error_log do Apache ou Nginx, geralmente acessível pelo cPanel ou solicitando à sua hospedagem.
• Aumente recursos temporariamente: Adicione define('WP_MEMORY_LIMIT', '512M'); e set_time_limit(600); no wp-config.php para descartar limites de execução.
• Force o log do PHP: Crie um arquivo php.ini na raiz do site com a diretiva error_log = /home/seuusuario/public_html/php-error.log.

Segurança: protegendo o debug.log

Por padrão, o arquivo debug.log fica dentro da pasta publicamente acessível /wp-content/. Qualquer visitante que saiba o caminho pode lê-lo, expondo informações internas do seu site. Para bloquear esse acesso, adicione a seguinte regra ao arquivo .htaccess na raiz do WordPress:

<Files "debug.log">
  Order Allow,Deny
  Deny from all
</Files>

Além disso, lembre-se de desativar WP_DEBUG e WP_DEBUG_LOG assim que o diagnóstico for concluído. Deixá-los ativos em produção não só representa um risco de segurança como também pode degradar a performance, já que o WordPress escreve logs a cada operação.

Com o debug.log dominado, você transforma erros genéricos de banco de dados em ações corretivas rápidas e precisas. Da próxima vez que uma tela branca ou um erro 500 aparecer, o caminho para a solução estará claro — e documentado linha a linha no seu log de depuração.