Cómo solucionar el error ‘failed to resolve handle’ de Mastodon entre instancias

Cuando intentas seguir a un usuario en una instancia diferente de Mastodon, el cuadro de búsqueda puede devolver un mensaje de error en rojo que dice “Failed to resolve handle”. Esto ocurre porque tu instancia no puede localizar la cuenta del usuario remoto a través del protocolo ActivityPub. El formato del identificador, como @user@example.social, requiere que tu instancia realice una consulta WebFinger en el servidor remoto. Si la consulta falla, el identificador no se puede resolver.

Este artículo explica por qué falla la consulta WebFinger y proporciona métodos paso a paso para solucionar el problema. Aprenderás a verificar el estado del servidor remoto, usar métodos de búsqueda alternativos y configurar tu propia instancia para mejorar la fiabilidad de la federación. Estas soluciones se aplican tanto a los administradores de instancias de Mastodon como a los usuarios habituales que no pueden seguir cuentas en otros servidores.

Por qué Mastodon no puede resolver identificadores remotos

Mastodon utiliza el protocolo ActivityPub para federarse con otras instancias. Cuando escribes un identificador en el cuadro de búsqueda, el cliente envía una solicitud al endpoint de la API de tu instancia /api/v2/search. Tu instancia realiza entonces una consulta WebFinger en el servidor remoto enviando una solicitud GET a https://remoteinstance.com/.well-known/webfinger?resource=acct:user@remoteinstance.com.

El endpoint de WebFinger devuelve un documento JSON que contiene la URL del actor de ActivityPub del usuario y otros enlaces de perfil. Si el servidor remoto no es accesible, devuelve un estado HTTP distinto de 200, o la cuenta de usuario no existe, tu instancia muestra el error “Failed to resolve handle”. Las causas comunes incluyen:

• La instancia remota está fuera de línea o experimenta una latencia alta. La solicitud WebFinger agota el tiempo de espera después de 10 segundos de forma predeterminada.
• La instancia remota bloquea tu instancia. Los bloqueos de dominio o la configuración de silencio impiden las consultas federadas.
• El formato del identificador es incorrecto. Espacios adicionales, un nombre de dominio incorrecto o la falta de símbolos @ provocan fallos de análisis.
• La instancia remota utiliza un software diferente que no implementa WebFinger correctamente. Algunas instancias de Pleroma o Misskey pueden tener respuestas no estándar.
• El resolutor DNS de tu instancia no puede resolver el dominio remoto. Los fallos de DNS impiden la conexión inicial.

Limitaciones de federación y filtros de seguridad

Los administradores de la instancia pueden configurar ALLOWED_DOMAIN_BLOCKS y BLACKLISTED_DOMAIN_BLOCKS en la configuración del entorno. Si un dominio remoto está bloqueado a nivel de instancia, todos los intentos de resolución de identificadores hacia ese dominio fallarán. Además, la configuración MEDIA_CACHE_BASE_URL, si está mal configurada, puede hacer que las solicitudes WebFinger se enruten incorrectamente a través de una CDN que no reenvía la solicitud al servidor de origen correcto.

Pasos para resolver el error de identificador

Sigue estos pasos en orden. Prueba el identificador después de cada paso para ver si se resuelve el error.

1. Verifica el formato del identificador
   Asegúrate de que el identificador esté escrito exactamente como @username@domain.tld sin espacios al principio ni al final. No incluyas el prefijo https://. Ejemplo: @gargron@mastodon.social. Si no estás seguro del nombre de usuario exacto, visita la página de perfil del usuario en su instancia y copia el identificador desde la URL o el encabezado del perfil.
2. Comprueba si la instancia remota está en línea
   Abre un navegador web y navega a la página de inicio de la instancia remota (por ejemplo, https://mastodon.social). Si la página carga, la instancia está en línea. Si no carga, la instancia puede estar en mantenimiento o cerrada permanentemente. Utiliza una herramienta de monitoreo de sitios web como DownForEveryoneOrJustMe para confirmar el estado.
3. Prueba el endpoint de WebFinger directamente
   Abre una nueva pestaña del navegador e introduce la siguiente URL, reemplazando user y remoteinstance.com con los valores reales:
   https://remoteinstance.com/.well-known/webfinger?resource=acct:user@remoteinstance.com
   Si el endpoint devuelve una respuesta JSON con un campo subject, el servidor remoto está funcionando. Si devuelve un error 404, el usuario no existe o la instancia no admite WebFinger. Si devuelve un error 403 o 410, la instancia está bloqueando la solicitud.
4. Usa la URL del perfil como búsqueda alternativa
   En el cuadro de búsqueda de Mastodon, pega la URL completa del perfil del usuario, como https://remoteinstance.com/@user. Mastodon intentará obtener el objeto actor de ActivityPub directamente desde esa URL, evitando el paso de análisis del identificador. Si la obtención tiene éxito, el usuario aparecerá en los resultados de búsqueda y podrás seguirlo.
5. Pide al usuario remoto que te envíe un mensaje directo o una mención
   Si tienes otra forma de contactar al usuario (correo electrónico, otra plataforma social), pídele que envíe una mención pública o un mensaje directo a tu identificador de Mastodon. Su instancia enviará el mensaje a tu instancia a través de ActivityPub, lo que crea una copia local del perfil del usuario. Una vez que llegue el mensaje, el identificador se resolverá automáticamente.
6. Reinicia los procesos sidekiq y web de Mastodon (solo administradores)
   Si eres el administrador de la instancia, conéctate por SSH a tu servidor y ejecuta:
   systemctl restart mastodon-sidekiq mastodon-web
   Esto borra cualquier caché de conexión obsoleta y reinicializa el grupo de clientes HTTP. Después de reiniciar, intenta la búsqueda del identificador de nuevo.
7. Revisa la lista de dominios bloqueados de la instancia (solo administradores)
   Inicia sesión en la interfaz de administración de Mastodon. Navega a Administración > Configuración del servidor > Federación > Dominios bloqueados. Comprueba si el dominio de la instancia remota está en la lista. Si está bloqueado, elimina el bloqueo o cambia la severidad a “Ninguna”. Guarda los cambios y vuelve a intentar la resolución del identificador.
8. Vacía la caché de DNS en el servidor de Mastodon (solo administradores)
   En el servidor, ejecuta:
   systemd-resolve --flush-caches (si usas systemd-resolved) o service nscd restart (si usas nscd). Esto borra cualquier registro DNS obsoleto que pueda estar apuntando a la dirección IP incorrecta para la instancia remota.

Si Mastodon sigue sin resolver el identificador

El identificador se resuelve en una instancia pero no en otra

Esto indica un problema de federación específico de tu instancia en lugar de un problema global. Comprueba si tu instancia está en modo de federación limitada o tiene una lista blanca habilitada. Si WHITELIST_MODE=true está configurado en el entorno, tu instancia solo se federará con instancias añadidas explícitamente a una lista blanca. Elimina la lista blanca o añade la instancia remota a ella.

El endpoint de WebFinger devuelve un estado 410 Gone

Un estado 410 significa que la cuenta de usuario ha sido eliminada o trasladada a otra instancia. Mastodon devuelve “Failed to resolve handle” porque el servidor remoto indica explícitamente que el recurso ya no está disponible. En este caso, no puedes seguir ese identificador. Busca el nuevo identificador o la URL del perfil del usuario en la nueva instancia.

La instancia remota utiliza un puerto no estándar o un certificado HTTPS

Algunas instancias se ejecutan en puertos personalizados (por ejemplo, 8443) o utilizan certificados autofirmados. El cliente HTTP de Mastodon rechaza las conexiones que no tienen un certificado TLS válido. Si controlas la instancia remota, instala un certificado válido de Let’s Encrypt. Si no, contacta al administrador de la instancia para que corrija el certificado.

Resolución de identificadores en Mastodon: WebFinger vs búsqueda directa por URL

Elemento	Consulta WebFinger	Búsqueda directa por URL
Tipo de solicitud	GET /.well-known/webfinger?resource=acct:user@domain	GET /@user o GET /users/user con Accept: application/activity+json
Dependencia del servidor remoto	Requiere que el endpoint de WebFinger sea accesible y devuelva JSON válido	Requiere que el servidor web remoto sirva el objeto actor de ActivityPub
Formato de identificador requerido	Identificador completo con @user@domain	URL completa del perfil (https://domain/@user) o cualquier URL que redirija al JSON del actor
Razones comunes de fallo	Instancia remota fuera de línea, dominio bloqueado, fallo de DNS, sintaxis de identificador incorrecta	Instancia remota fuera de línea, URL del perfil cambiada, política CORS que bloquea la obtención
Tasa de éxito cuando el remoto funciona	Alta para instancias estándar de Mastodon	Alta para cualquier software compatible con ActivityPub

Después de resolver el error de identificador, puedes seguir al usuario y ver sus publicaciones en tu cronología de inicio. Si eres administrador de una instancia, considera habilitar la variable de entorno DIRECT_FETCH_ENABLED, que obliga a Mastodon a intentar siempre una obtención directa por URL antes de recurrir a WebFinger. Esto reduce los fallos de resolución para instancias con implementaciones de WebFinger no estándar.