Erro 500 do WordPress após atualizar um plugin

O que este erro significa e como reconhecê-lo

• O site funcionava antes de um plugin ser atualizado; depois, o front-end, o painel do WordPress ou ambos começaram a retornar erros HTTP 500.
• A falha pode ocorrer após uma atualização manual ou automática do plugin.
• O site público pode carregar enquanto o /wp-admin/ falha, ou somente páginas e requisições que usam o plugin atualizado podem apresentar erro.
• O navegador pode exibir um “500 Internal Server Error” genérico, uma página em branco ou uma mensagem de erro crítico do WordPress, em vez da causa subjacente.
• Renomear o diretório do plugin atualizado recentemente pode fazer o site voltar a carregar.
• O log de depuração do servidor ou do WordPress pode conter um erro fatal do PHP, um erro de sintaxe, um erro de arquivo ausente ou uma mensagem que identifica o plugin atualizado.

Causas principais, por probabilidade

1. Incompatibilidade com o PHP: A nova versão do plugin pode exigir um recurso ou uma versão do PHP que o servidor não oferece.
2. Conflito entre plugin, tema ou WordPress: A atualização pode interagir de forma inadequada com outra extensão, o tema ativo ou a versão instalada do core do WordPress. Declarações duplicadas de funções ou classes são pistas comuns.
3. Atualização incompleta ou corrompida: Um timeout, uma conexão interrompida ou uma transferência de arquivos malsucedida pode deixar arquivos do plugin ausentes ou danificados.
4. Regressão do plugin: A nova versão pode conter um defeito que afeta a configuração deste site, mesmo quando os requisitos informados de PHP e WordPress são atendidos.
5. Outro problema ou um problema mais amplo na hospedagem: Se desativar o plugin atualizado não mudar nada, a resposta 500 pode estar relacionada a outra alteração recente, à configuração do PHP, a permissões, a limites de recursos ou a uma falha no nível do servidor.

Como corrigir

1. Confirme o momento e o alcance da falha

Identifique o plugin atualizado imediatamente antes do surgimento do erro. Se vários plugins foram atualizados juntos, registre todos eles. Verifique o site público, o /wp-admin/ e qualquer recurso específico do plugin que esteja falhando. Evite atualizações não relacionadas até testar a causa suspeita.

2. Desative o plugin atualizado sem usar o painel

Antes de alterar arquivos, confirme que você tem acesso autorizado ao site por SFTP ou pelo gerenciador de arquivos da hospedagem e, quando possível, um backup atual. Abra wp-content/plugins/ e renomeie o diretório do plugin suspeito adicionando um sufixo como -disabled.

Recarregue o front-end e o /wp-admin/:

• Se o site voltar a funcionar, mantenha o plugin desativado enquanto examina os logs e escolhe entre fazer rollback ou aplicar uma correção de compatibilidade.
• Se nada mudar, restaure o nome original do diretório e teste o próximo plugin atualizado ao mesmo tempo.
• Se o erro continuar depois que todos os plugins atualizados recentemente forem desativados, examine os logs do servidor e do PHP e revise outras alterações recentes na hospedagem ou na configuração.

Renomear um diretório altera quais plugins o WordPress carrega; portanto, não use isso como substituto para identificar e corrigir o problema subjacente.

3. Capture o erro subjacente do PHP

Uma resposta 500 é apenas o sintoma externo. Se você tiver autorização para editar o wp-config.php, ative temporariamente o registro de logs acima da linha que indica que a edição foi interrompida:

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

Com o plugin suspeito ainda desativado, preserve o log atual, se necessário. Reative o plugin somente quando estiver pronto para reproduzir a falha; depois, reproduza-a uma vez e examine wp-content/debug.log e o log de erros do PHP ou do servidor no painel da hospedagem. Procure o nome do plugin, uma mensagem sobre a versão do PHP, um arquivo ausente, um erro de sintaxe, Cannot redeclare function ou Cannot declare class.

O registro de depuração pode gravar detalhes confidenciais da implementação e deve ser temporário. Desative as configurações após os testes, especialmente em um site público de produção, e remova ou proteja os dados de log expostos de acordo com os procedimentos da sua hospedagem.

4. Relacione a mensagem do log à causa provável

• Um recurso do PHP não compatível ou uma versão obrigatória do PHP aponta para um problema de compatibilidade com o PHP.
• Uma mensagem que identifica duas extensões ou um tema junto de Cannot redeclare function ou Cannot declare class aponta para um conflito de compatibilidade.
• Um arquivo ausente, um erro de sintaxe ou um erro dentro do diretório do plugin atualizado recentemente sugere uma atualização incompleta ou corrompida.
• Um erro que identifica o core do WordPress ou outra extensão pode indicar que a atualização revelou um problema de compatibilidade mais amplo.
• Se o log não identificar o plugin nem um componente relacionado, verifique os erros no nível da hospedagem antes de presumir que a atualização é responsável.

5. Faça rollback para a última versão conhecida por funcionar

Se o site precisar ser restaurado rapidamente, preserve uma cópia dos arquivos atuais do plugin e use um backup verificado ou um pacote antigo da fonte de distribuição estabelecida do plugin. Envie ou restaure-o por SFTP ou pelo gerenciador de arquivos da hospedagem e, depois, teste o site antes de reativar o plugin.

Não substitua a única cópia de um backup funcional. Mantenha as atualizações automáticas desativadas ou sob revisão para esse plugin até entender a causa e haver uma versão compatível disponível.

6. Verifique os requisitos do PHP e do WordPress

Compare as versões mínimas declaradas de PHP e WordPress da versão atualizada do plugin com as versões reais do site. Quando o painel estiver disponível, as informações do PHP geralmente são exibidas em Ferramentas → Saúde do site → Informações; o painel de controle da hospedagem também pode mostrar a versão ativa do PHP.

Se o PHP ou o WordPress estiver abaixo do requisito do plugin, faça um backup e confirme a compatibilidade com o tema, outros plugins e o ambiente de hospedagem antes de atualizar. Se a hospedagem controlar o PHP, pergunte ao provedor sobre o caminho de atualização compatível. Não altere a versão do PHP em produção sem verificar, pois isso pode afetar o restante do site.

7. Encaminhe um conflito ou uma regressão confirmados

Mantenha a atualização incompatível desativada ou restaure a última versão conhecida por funcionar enquanto informa o erro fatal exato, as versões do plugin, a versão do PHP, a versão do WordPress e as etapas para reproduzir o problema aos desenvolvedores do plugin ou do tema responsáveis. Evite editar permanentemente os arquivos do plugin: uma atualização futura pode sobrescrever essas alterações e deixar o site sem suporte.

Prevenção e como verificar a correção

• Crie e verifique um backup do banco de dados e dos arquivos do site antes de atualizar plugins.
• Atualize os plugins individualmente quando possível, para que uma falha possa ser associada a uma alteração específica.
• Teste alterações importantes em plugins, no WordPress e no PHP em uma cópia de staging antes de aplicá-las em produção.
• Mantenha o PHP e o WordPress dentro das faixas compatíveis indicadas pelos plugins e pelo tema.
• Após cada atualização, teste o site público, o /wp-admin/, o login, os formulários e os recursos fornecidos pelo plugin atualizado.
• Revise as atualizações automáticas de plugins essenciais para o negócio ou que tenham histórico de problemas de compatibilidade.
• Mantenha disponível uma versão documentada do plugin conhecida por funcionar e um método de recuperação.
• Desative as configurações temporárias de exibição e registro de depuração após a solução de problemas e proteja ou remova os logs que contenham detalhes internos dos erros.

Perguntas frequentes