Imagine: terminou de escrever um artigo, clicou em «Publicar» e o WordPress mostra um banner vermelho com um erro. Atualizar a página? O mesmo erro. Sair e voltar a entrar no painel de administração? Nada muda. O artigo ficou preso nos rascunhos e o tempo está a esgotar-se.

O erro «A atualização falhou» ou «A publicação falhou» é um daqueles problemas que nos deixa perplexos: a mensagem não diz o que exatamente se avariou. Mas, após anos a trabalhar com o WordPress, desenvolvemos uma sequência de diagnóstico clara. Na maioria dos casos, a causa está à superfície e a correção demora apenas alguns minutos.

Neste guia, encontrará 7 métodos comprovados: desde os mais simples (ligação à internet e URL do site) até à depuração direcionada através do wp-config e ao trabalho com plugins. Cada passo inclui ações específicas e capturas de ecrã do painel de administração.

💡 Visão geral rápida:

• Verifique a sua ligação à internet e o URL do site nas definições
• Abra «Ferramentas → Saúde do Site» e verifique o estado da API REST
• Ative o modo de depuração através de WP_DEBUG no wp-config.php
• Elimine o ficheiro temporário .maintenance do servidor via FTP
• Desative todos os plugins de uma vez e depois ative-os um a um para identificar o conflito
• Substitua temporariamente o Gutenberg pelo Classic Editor para excluir um conflito do editor de blocos
• Se nada funcionar, contacte o seu fornecedor de alojamento ou a comunidade WordPress

1. Verifique a sua ligação à internet e o URL do site

A causa mais simples (e, por isso, muitas vezes ignorada): o WordPress perde a ligação ao servidor a meio de um pedido.

Abra outro separador do navegador e visite qualquer site. A página carregou? A sua internet está a funcionar. Se não, restaure a ligação e tente publicar o artigo novamente.

Se a internet estiver bem, o próximo suspeito são as definições de URL. Após anos de migrações, alterações de domínio e experiências com HTTPS, os endereços em «Definições → Gerais» por vezes divergem da realidade. Vá até lá e compare dois campos: Endereço do WordPress (URL) e Endereço do site (URL). Devem corresponder ao endereço real que usa para aceder ao painel de administração.

Se ambos os endereços estiverem corretos, mas o erro persistir, vamos aprofundar.

2. Verifique o estado da API REST

A API REST do WordPress é o mecanismo através do qual o editor Gutenberg comunica com o servidor. Quando a API REST não responde ou devolve um erro, o botão «Publicar» deixa de funcionar.

Felizmente, o WordPress 5.2 e versões posteriores incluem uma ferramenta de diagnóstico integrada. Vá a Ferramentas → Saúde do Site. Desça até à secção «Melhorias recomendadas» e procure a linha «A API REST encontrou um resultado inesperado» ou um erro semelhante.

Se a API REST mostrar um erro, expanda a informação de depuração no próprio local, no separador «Informação» → «API REST». Verá a chamada específica que falhou e o código de resposta do servidor. Na maioria das vezes, o problema reside em:

• Um plugin de segurança a bloquear pedidos REST (Wordfence, iThemes/Solid Security com definições agressivas de firewall);
• Código personalizado no functions.php que quebra acidentalmente os endpoints REST;
• Um plugin de cache a servir uma resposta da API REST em cache.

Desative o plugin suspeito e verifique novamente o estado da API REST na mesma página.

3. Ative o modo de depuração do WordPress

Quando o problema não é óbvio, precisa de o «iluminar». O WordPress tem um modo de depuração integrado para este fim.

Precisará de acesso aos ficheiros do site. Um cliente FTP (FileZilla, WinSCP) ou o gestor de ficheiros no seu painel de alojamento funcionarão. Antes de fazer qualquer edição de ficheiros, crie uma cópia de segurança. Um erro no wp-config.php pode deitar o site abaixo, mas uma cópia de segurança restaurará tudo num minuto.

Passos a seguir:

• Ligue-se ao servidor via FTP e encontre a pasta raiz do WordPress (onde estão wp-content, wp-admin e wp-includes).
• Encontre o ficheiro wp-config.php e transfira-o para o seu computador.
• Abra o ficheiro num editor de texto (Notepad++, Sublime Text, não o Word ou o Bloco de Notas, que podem corromper a codificação).
• No final, antes da linha /* That's all, stop editing! Happy publishing. */, adicione:

1
define('WP_DEBUG', true);
2
define('WP_DEBUG_LOG', true);
3
define('WP_DEBUG_DISPLAY', false);

A primeira linha ativa a depuração, a segunda escreve os erros no ficheiro wp-content/debug.log (sem os mostrar aos visitantes) e a terceira oculta os erros da exibição do site.

Guarde o ficheiro e carregue-o de volta para o servidor, substituindo o original. Agora tente publicar um artigo. Se o erro desaparecer, a causa era um aviso PHP que estava a interromper a resposta REST. Abra o wp-content/debug.log através do mesmo FTP e procure entradas com PHP Notice ou PHP Warning. Elas apontarão para o plugin problemático.

Quando terminar, certifique-se de desativar o WP_DEBUG, substituindo true por false. Caso contrário, o debug.log crescerá indefinidamente.

Se o erro se mantiver, prossigamos.

4. Elimine o ficheiro.maintenance

O WordPress cria um ficheiro temporário .maintenance na raiz do site durante as atualizações do núcleo, plugins e temas. Isto coloca o site em modo de manutenção e os visitantes veem a mensagem «Brevemente indisponível para manutenção programada. Volte dentro de um minuto.»

Por vezes, a atualização termina, mas o .maintenance permanece. O WordPress pensa que a manutenção ainda está em curso e bloqueia a publicação.

Abra o FTP novamente, vá à pasta raiz e encontre o ficheiro .maintenance (com um ponto no início, está oculto; no FileZilla, ative a exibição de ficheiros ocultos através de «Servidor → Forçar a exibição de ficheiros ocultos»).

Elimine o .maintenance e verifique imediatamente a publicação. O efeito dura cerca de 10 minutos (o WordPress recria o ficheiro se uma atualização ainda estiver ativa). Se o erro desaparecer, mas voltar após 10 minutos, uma atualização em segundo plano ainda está em execução. Aguarde ou force a sua conclusão através de «Plugins → Plugins instalados» (verá o estado da atualização lá).

5. Encontre o plugin em conflito

A causa mais comum de erros de publicação são os conflitos de plugins. Um plugin quebra a API REST, outro interfere com o processo de gravação e um terceiro entra em conflito com o Gutenberg.

A forma rápida de encontrar o culpado é a desativação em massa com reativação sequencial:

• Vá a Plugins → Plugins instalados.
• Marque a caixa de verificação «Plugin» no cabeçalho da tabela para selecionar todos.
• No menu suspenso «Ações em massa», selecione «Desativar» e clique em «Aplicar».

Agora todos os plugins estão desativados. Tente publicar um artigo. Funcionou? Ótimo, a causa é um dos plugins. Ative-os um a um e verifique a publicação após cada um. Assim que o erro voltar, encontrou o culpado.

O que fazer com o plugin problemático:

• Atualize-o para a versão mais recente (o programador pode já ter corrigido o erro).
• Contacte o suporte do plugin com detalhes: versão do WordPress, versão do plugin e que ação desencadeia o erro.
• Substitua-o temporariamente por uma alternativa até que o programador lance uma correção.

6. Substitua temporariamente o Gutenberg pelo Classic Editor

O editor de blocos Gutenberg apareceu no WordPress 5.0 e percorreu um longo caminho desde então. Mas ainda ocorrem conflitos com certos plugins e temas, especialmente com construtores de páginas mais antigos (WPBakery, versões antigas do Elementor) e plugins que não estão adaptados à API REST.

O Classic Editor não usa a API REST para guardar. Funciona através do antigo admin-ajax.php. Portanto, instalá-lo é um teste rápido: se o erro desaparecer, o problema está especificamente na combinação Gutenberg + algum plugin.

Instale o Classic Editor, o plugin oficial da equipa do WordPress:

• Plugins → Adicionar novo.
• Na pesquisa, escreva «Classic Editor».
• Clique em «Instalar agora» e depois em «Ativar».

Após a ativação, tente publicar um artigo através do editor clássico. Funciona? Então o conflito está do lado do Gutenberg.

Importante: este é um passo de diagnóstico, não uma solução permanente. O Classic Editor desativa o editor de blocos e perde todas as capacidades do Gutenberg: blocos, modelos, formatação integrada. Assim que encontrar o plugin problemático (usando o método do passo 5), remova o Classic Editor e volte ao Gutenberg com um ambiente corrigido.

7. Procure ajuda

Se completou todos os seis passos e o erro persiste, o problema provavelmente está mais profundo: ao nível do servidor, do alojamento ou de um raro erro do núcleo do WordPress.

Eis a quem recorrer, por ordem de eficácia:

Fornecedor de alojamento. Contacte o suporte deles com detalhes: versão do WordPress, versão do PHP, que plugins estão ativos e que ação desencadeia o erro. O alojador tem acesso aos registos do servidor e muitas vezes consegue detetar a causa num minuto (espaço em disco esgotado, um módulo PHP está desativado, limite de memória excedido).

Fóruns do WordPress. O fórum de suporte oficial do WordPress.org é uma comunidade viva onde os programadores do núcleo e autores de plugins respondem. Abra um tópico, anexe capturas de ecrã e o resultado do debug.log.

Após ler este guia, tem uma cadeia de diagnóstico completa: desde um clique do rato até à edição de ficheiros do servidor. Em 9 de cada 10 casos, o problema resolve-se com os passos 1 a 5, sem FTP ou wp-config.

Abaixo encontrará respostas às perguntas mais comuns e um vídeo para reforçar o material.

⁉️🤔 Perguntas frequentes

Porque é que o erro ocorre logo após a atualização do WordPress?

Muito provavelmente, um dos plugins é incompatível com a nova versão do núcleo ou com a nova versão do PHP que o alojamento ativou juntamente com a atualização. Siga o passo 5 (desativação em massa) e encontrará rapidamente o culpado.

Posso simplesmente reinstalar o WordPress sem investigar?

Reinstalar o núcleo através de «Atualizações → Reinstalar agora» é seguro e não toca no conteúdo/plugins. Mas se o erro for causado por um conflito de plugins, reinstalar o núcleo não ajudará. É melhor gastar 5 minutos nos passos de diagnóstico acima do que tentar soluções aleatórias às cegas.

Porque é que o erro aparece apenas num artigo, enquanto outros publicam normalmente?

A causa provável é o conteúdo do próprio artigo. Alguma combinação de blocos Gutenberg, um iframe incorporado ou um script está a causar uma falha durante a gravação. Tente copiar o conteúdo para um novo artigo e publicá-lo. Se o novo artigo for publicado com sucesso, elimine o antigo e trabalhe com a cópia.

Devo manter o Classic Editor permanentemente após corrigir o problema?

Não. O Classic Editor é uma solução de diagnóstico temporária. Assim que encontrar e corrigir o plugin em conflito, remova o Classic Editor e volte ao Gutenberg. O editor de blocos é o padrão do WordPress e não deve abandoná-lo sem um motivo sério.

O que devo fazer se não tiver acesso FTP?

Use o gestor de ficheiros no seu painel de alojamento (cPanel → Gestor de Ficheiros, ISPmanager → Ficheiros). Funcionalmente, faz o mesmo. Se também não estiver disponível, contacte o suporte do seu alojamento e eles ajudá-lo-ão a obter acesso.

Qual o método que deve tentar primeiro?

A fórmula universal: verifique a internet (10 segundos) → veja a Saúde do Site (30 segundos) → desative plugins em massa (1 minuto). Na maioria dos casos, o problema já fica resolvido nesta fase.

Se o erro voltar após uma correção, encontrou um sintoma em vez da causa raiz. Ative o WP_DEBUG_LOG (passo 3) e recolha um registo completo. Ele mostrará o ficheiro e a linha exata com o erro. Com este registo, pode contactar a equipa de suporte do plugin ou o fórum do WordPress.

E o mais importante: mantenha sempre uma cópia de segurança recente. Ela transforma qualquer falha de uma catástrofe num atraso de cinco minutos.