Como Corrigir o Erro ‘Webfinger Lookup Failed’ no Mastodon ao Mencionar

Ao tentar mencionar um usuário de outra instância do Mastodon digitando o handle completo, você pode ver o erro “Webfinger Lookup Failed.” Esse erro impede que a menção seja resolvida e a postagem seja enviada. A causa geralmente é um problema de DNS ou configuração do servidor que impede o Mastodon de encontrar a conta do usuário via Webfinger. Este artigo explica por que o erro ocorre e fornece correções passo a passo tanto para administradores de instância quanto para usuários comuns.

Por que a Consulta Webfinger Falha para Menções

Webfinger é um protocolo que o Mastodon usa para traduzir um handle usuário@domínio em uma URL de actor ActivityPub. Quando você digita @usuário@exemplo.com em uma postagem, sua instância envia uma requisição HTTP para https://exemplo.com/.well-known/webfinger?resource=acct:usuário@exemplo.com. O servidor de destino deve responder com um objeto JSON contendo a URL do perfil do usuário. Se qualquer parte dessa cadeia falhar, o Mastodon exibe o erro de consulta.

Pontos comuns de falha incluem:

• Registros DNS para o domínio de destino ausentes ou incorretos.
• O servidor web (Nginx ou Apache) da instância de destino bloqueia o diretório .well-known.
• O serviço Mastodon na instância de destino está inativo ou sobrecarregado.
• Um proxy reverso ou CDN armazena em cache uma resposta antiga ou vazia.
• A conta de usuário não existe, foi movida ou excluída.

Passos para Diagnosticar e Corrigir o Erro Webfinger Lookup Failed

Siga estes passos em ordem. Comece com verificações básicas e prossiga para correções no servidor, se necessário.

1. Verifique se o handle do usuário está correto
   Confira se você digitou o handle exatamente como @usuário@domínio. O domínio deve corresponder à instância de origem do usuário. Um erro de digitação em qualquer parte faz a consulta falhar imediatamente.
2. Teste o endpoint Webfinger manualmente
   Abra um navegador ou use curl para solicitar https://domínio/.well-known/webfinger?resource=acct:usuário@domínio. Substitua domínio e usuário pelos valores reais. Uma resposta bem-sucedida retorna HTTP 200 e um corpo JSON com um campo subject. Se você receber um 404 ou uma resposta vazia, o problema está no servidor de destino.
3. Verifique o registro DNS A do domínio de destino
   Use uma ferramenta como nslookup domínio ou dig A domínio a partir do seu servidor. O domínio deve resolver para um endereço IP que execute uma instância do Mastodon. Se o registro DNS estiver ausente ou apontar para um servidor diferente, a requisição Webfinger não conseguirá alcançar o host correto.
4. Inspecione a configuração do Nginx ou Apache no servidor de destino
   Na instância de destino, verifique se o servidor web permite acesso ao caminho /.well-known/. Para Nginx, garanta que o bloco de localização para /.well-known/ não esteja restrito. Usuários de Apache devem verificar se AllowOverride ou RewriteRule não bloqueia o diretório.
5. Reinicie o serviço web do Mastodon na instância de destino
   Se a instância de destino estiver em manutenção ou sobrecarregada, reinicie o processo web. Em uma configuração típica do Mastodon, execute systemctl restart mastodon-web ou docker-compose restart web dependendo da implantação. Após reiniciar, teste o endpoint Webfinger novamente.
6. Limpe o cache Webfinger na sua própria instância
   Sua instância do Mastodon armazena em cache os resultados Webfinger para reduzir a carga. Se uma consulta anterior falhou, o cache da falha pode bloquear tentativas futuras. Execute RAILS_ENV=production bin/tootctl cache clear a partir do diretório do Mastodon no seu servidor. Isso limpa todos os valores em cache, incluindo respostas Webfinger.
7. Verifique o cache de CDN ou proxy reverso
   Se a instância de destino usa Cloudflare, Fastly ou outro CDN, o CDN pode armazenar em cache uma resposta 404. Limpe o cache para a URL específica /.well-known/webfinger. No Cloudflare, use a opção Purge Cache na aba Caching. Aguarde alguns minutos e teste novamente.
8. Verifique se a conta de usuário está ativa e não foi movida
   Faça login na instância de destino como administrador e verifique o status da conta do usuário. Se o usuário moveu sua conta para outra instância usando o recurso Move, o handle antigo retorna uma resposta 410 Gone. Você deve usar o novo handle.

Se a Consulta Webfinger Ainda Falhar Após a Correção Principal

Webfinger retorna HTTP 500 da instância de destino

Um erro de servidor indica um problema com o aplicativo Mastodon na instância de destino. Verifique os logs do Mastodon com journalctl -u mastodon-web -n 50 ou revise o arquivo log/production.log. Causas comuns incluem falhas de conexão com o banco de dados, dependências ausentes ou um registro de usuário corrompido. Reiniciar o processo sidekiq do Mastodon com systemctl restart mastodon-sidekiq geralmente resolve erros transitórios.

Webfinger retorna redirecionamento HTTP 301 ou 302

Um redirecionamento significa que o servidor de destino está configurado para encaminhar a requisição para uma URL diferente. O Mastodon segue redirecionamentos por padrão, mas se a cadeia de redirecionamento levar a um servidor que não é Mastodon ou a um domínio que não atende Webfinger, a consulta falha. Verifique o destino do redirecionamento inspecionando o cabeçalho Location na resposta. Se o redirecionamento apontar para um domínio diferente, atualize o handle do usuário para corresponder ao domínio final.

Webfinger funciona de uma instância, mas não de outra

Se você consegue resolver um usuário do seu navegador desktop, mas não da sua instância do Mastodon, o problema provavelmente é a resolução DNS no seu servidor. O resolvedor DNS da sua instância pode não ter os registros corretos. Edite /etc/resolv.conf no seu servidor para usar um resolvedor DNS público como 8.8.8.8 ou 1.1.1.1. Após alterar o resolvedor, reinicie o serviço web do Mastodon e limpe o cache novamente.

Item	Correção Local (Sua Instância)	Correção Remota (Instância de Destino)
Causa do erro	Cache de consulta falha ou configuração DNS incorreta no seu servidor	Registro DNS A ausente, caminho .well-known bloqueado ou serviço Mastodon inativo
Correção principal	Limpar cache com bin/tootctl cache clear	Corrigir registro DNS A ou desbloquear .well-known na configuração do servidor web
Ferramenta de verificação	curl para o endpoint Webfinger da sua própria instância	curl diretamente para o endpoint Webfinger do domínio de destino
Tempo para aplicar	Menos de 1 minuto	5 a 30 minutos dependendo da propagação DNS

Após concluir as correções, teste a menção novamente digitando @usuário@domínio em uma nova postagem. A menção deve resolver para o nome de exibição do usuário e o link do perfil. Se o erro persistir, repita os passos com atenção extra à configuração do servidor web na instância de destino. Você também pode pedir ao administrador da instância de destino para executar RAILS_ENV=production bin/tootctl accounts refresh [usuário] para forçar uma atualização da conta de usuário.