Como corrigir o erro ‘Falha ao resolver handle’ no Mastodon entre instâncias

Quando você tenta seguir um usuário em uma instância diferente do Mastodon, a caixa de pesquisa pode exibir uma mensagem de erro vermelha informando “Falha ao resolver handle”. Isso ocorre porque sua instância não consegue localizar a conta do usuário remoto através do protocolo ActivityPub. O formato do handle, como @usuario@exemplo.social, exige que sua instância realize uma consulta WebFinger no servidor remoto. Se a consulta falhar, o handle não pode ser resolvido.

Este artigo explica por que a consulta WebFinger falha e fornece métodos passo a passo para corrigir o problema. Você aprenderá a verificar o status do servidor remoto, usar métodos de pesquisa alternativos e configurar sua própria instância para melhorar a confiabilidade da federação. Essas soluções se aplicam tanto a administradores de instâncias do Mastodon quanto a usuários comuns que não conseguem seguir contas em outros servidores.

Por que o Mastodon falha ao resolver handles remotos

O Mastodon usa o protocolo ActivityPub para federar com outras instâncias. Quando você digita um handle na caixa de pesquisa, o cliente envia uma solicitação ao endpoint da API da sua instância /api/v2/search. Sua instância então realiza uma consulta WebFinger no servidor remoto enviando uma requisição GET para https://instanciaremota.com/.well-known/webfinger?resource=acct:usuario@instanciaremota.com.

O endpoint WebFinger retorna um documento JSON contendo a URL do actor ActivityPub do usuário e outros links do perfil. Se o servidor remoto estiver inacessível, retornar um status HTTP diferente de 200, ou a conta do usuário não existir, sua instância exibe o erro “Falha ao resolver handle”. Causas comuns incluem:

• A instância remota está offline ou com alta latência. A solicitação WebFinger expira após 10 segundos por padrão.
• A instância remota bloqueia sua instância. Bloqueios de domínio ou configurações de silenciamento impedem consultas federadas.
• O formato do handle está incorreto. Espaços extras, nome de domínio errado ou símbolos @ ausentes causam falhas na análise.
• A instância remota usa um software diferente que não implementa o WebFinger corretamente. Algumas instâncias Pleroma ou Misskey podem ter respostas não padronizadas.
• O resolvedor DNS da sua instância não consegue resolver o domínio remoto. Falhas de DNS impedem a conexão inicial.

Limitações de federação e filtros de segurança

Administradores de instância podem configurar ALLOWED_DOMAIN_BLOCKS e BLACKLISTED_DOMAIN_BLOCKS nas configurações de ambiente. Se um domínio remoto estiver bloqueado no nível da instância, todas as tentativas de resolução de handle para esse domínio falharão. Além disso, a configuração MEDIA_CACHE_BASE_URL, se mal ajustada, pode fazer com que as solicitações WebFinger sejam roteadas incorretamente através de um CDN que não encaminha a solicitação para o servidor de origem correto.

Passos para resolver o erro de handle

Siga estes passos em ordem. Teste o handle após cada etapa para verificar se o erro foi resolvido.

1. Verifique o formato do handle
   Certifique-se de que o handle foi digitado exatamente como @usuario@dominio.tld, sem espaços no início ou no final. Não inclua o prefixo https://. Exemplo: @gargron@mastodon.social. Se não tiver certeza do nome de usuário exato, visite a página de perfil do usuário na instância dele e copie o handle da URL ou do cabeçalho do perfil.
2. Verifique se a instância remota está online
   Abra um navegador e acesse a página inicial da instância remota (ex.: https://mastodon.social). Se a página carregar, a instância está online. Se não carregar, a instância pode estar em manutenção ou permanentemente fechada. Use uma ferramenta de monitoramento de sites como DownForEveryoneOrJustMe para confirmar o status.
3. Teste o endpoint WebFinger diretamente
   Abra uma nova aba do navegador e digite a seguinte URL, substituindo usuario e instanciaremota.com pelos valores reais:
   https://instanciaremota.com/.well-known/webfinger?resource=acct:usuario@instanciaremota.com
   Se o endpoint retornar uma resposta JSON com um campo subject, o servidor remoto está funcionando. Se retornar um erro 404, o usuário não existe ou a instância não suporta WebFinger. Se retornar um erro 403 ou 410, a instância está bloqueando a solicitação.
4. Use a URL do perfil como pesquisa alternativa
   Na caixa de pesquisa do Mastodon, cole a URL completa do perfil do usuário, como https://instanciaremota.com/@usuario. O Mastodon tentará buscar o objeto actor do ActivityPub diretamente dessa URL, ignorando a etapa de análise do handle. Se a busca for bem-sucedida, o usuário aparecerá nos resultados da pesquisa e você poderá segui-lo.
5. Peça ao usuário remoto para enviar uma mensagem direta ou menção
   Se você tiver outra forma de contatar o usuário (e-mail, outra rede social), peça que ele envie uma menção pública ou mensagem direta para o seu handle do Mastodon. A instância dele enviará a mensagem para sua instância via ActivityPub, o que cria uma cópia local do perfil do usuário. Após a mensagem chegar, o handle será resolvido automaticamente.
6. Reinicie os processos sidekiq e web do Mastodon (apenas administrador)
   Se você for o administrador da instância, acesse o servidor via SSH e execute:
   systemctl restart mastodon-sidekiq mastodon-web
   Isso limpa caches de conexão obsoletos e reinicializa o pool de clientes HTTP. Após reiniciar, tente a pesquisa do handle novamente.
7. Revise a lista de bloqueios de domínio da instância (apenas administrador)
   Faça login na interface de administração do Mastodon. Navegue até Administração > Configurações do Servidor > Federação > Bloqueios de Domínio. Verifique se o domínio da instância remota está listado. Se estiver bloqueado, remova o bloqueio ou altere a gravidade para “Nenhum”. Salve as alterações e tente resolver o handle novamente.
8. Limpe o cache DNS no servidor do Mastodon (apenas administrador)
   No servidor, execute:
   systemd-resolve --flush-caches (se estiver usando systemd-resolved) ou service nscd restart (se estiver usando nscd). Isso limpa registros DNS obsoletos que podem estar apontando para o endereço IP errado da instância remota.

Se o Mastodon ainda falhar ao resolver o handle

O handle resolve em uma instância, mas não em outra

Isso indica um problema de federação específico da sua instância, e não um problema global. Verifique se sua instância está em modo de federação limitada ou se possui uma whitelist ativada. Se WHITELIST_MODE=true estiver definido no ambiente, sua instância federará apenas com instâncias explicitamente adicionadas a uma whitelist. Remova a whitelist ou adicione a instância remota a ela.

O endpoint WebFinger retorna status 410 Gone

Um status 410 significa que a conta do usuário foi excluída ou movida para outra instância. O Mastodon retorna “Falha ao resolver handle” porque o servidor remoto informa explicitamente que o recurso não está mais disponível. Nesse caso, você não pode seguir esse handle. Pesquise pelo novo handle do usuário ou pela URL do perfil na nova instância.

A instância remota usa uma porta não padrão ou certificado HTTPS

Algumas instâncias rodam em portas personalizadas (ex.: 8443) ou usam certificados autoassinados. O cliente HTTP do Mastodon rejeita conexões que não possuem um certificado TLS válido. Se você controla a instância remota, instale um certificado válido do Let’s Encrypt. Se não, entre em contato com o administrador da instância para corrigir o certificado.

Resolução de handle no Mastodon: WebFinger vs Pesquisa por URL direta

Item	Consulta WebFinger	Pesquisa por URL direta
Tipo de requisição	GET /.well-known/webfinger?resource=acct:usuario@dominio	GET /@usuario ou GET /users/usuario com Accept: application/activity+json
Dependência do servidor remoto	Requer que o endpoint WebFinger esteja acessível e retorne JSON válido	Requer que o servidor web remoto sirva o objeto actor do ActivityPub
Formato do handle necessário	Handle completo com @usuario@dominio	URL completa do perfil (https://dominio/@usuario) ou qualquer URL que redirecione para o JSON do actor
Motivos comuns de falha	Instância remota offline, domínio bloqueado, falha de DNS, sintaxe incorreta do handle	Instância remota offline, URL do perfil alterada, política de CORS bloqueando a busca
Taxa de sucesso quando o remoto está funcionando	Alta para instâncias Mastodon padrão	Alta para qualquer software compatível com ActivityPub

Após resolver o erro de handle, você pode seguir o usuário e ver suas postagens na sua linha do tempo inicial. Se você é administrador de instância, considere ativar a variável de ambiente DIRECT_FETCH_ENABLED, que força o Mastodon a sempre tentar uma busca direta por URL antes de recorrer ao WebFinger. Isso reduz falhas de resolução para instâncias com implementações WebFinger não padronizadas.