How to Fix Mastodon ‘Failed to Resolve Handle’ Across Instances

When you try to follow a user on a different Mastodon instance, the search box might return a red error message stating “Failed to resolve handle.” This occurs because your instance cannot locate the remote user’s account through the ActivityPub protocol. The handle format, such as @user@example.social, requires your instance to perform a WebFinger lookup on the remote server. If the lookup fails, the handle cannot be resolved.

This article explains why the WebFinger lookup fails and provides step-by-step methods to fix the issue. You will learn how to check the remote server status, use alternative search methods, and configure your own instance to improve federation reliability. These solutions apply to both Mastodon instance administrators and regular users who cannot follow accounts on other servers.

Why Mastodon Fails to Resolve Remote Handles

Mastodon uses the ActivityPub protocol to federate with other instances. When you type a handle into the search box, the client sends a request to your instance’s API endpoint /api/v2/search. Your instance then performs a WebFinger lookup on the remote server by sending a GET request to https://remoteinstance.com/.well-known/webfinger?resource=acct:user@remoteinstance.com.

The WebFinger endpoint returns a JSON document containing the user’s ActivityPub actor URL and other profile links. If the remote server is unreachable, returns a non-200 HTTP status, or the user account does not exist, your instance displays the “Failed to resolve handle” error. Common causes include:

• Remote instance is offline or experiencing high latency. The WebFinger request times out after 10 seconds by default.
• The remote instance blocks your instance. Domain blocks or silence settings prevent federated lookups.
• The handle format is incorrect. Extra spaces, wrong domain name, or missing @ symbols cause parsing failures.
• The remote instance uses a different software that does not implement WebFinger correctly. Some Pleroma or Misskey instances may have nonstandard responses.
• Your instance’s DNS resolver cannot resolve the remote domain. DNS failures prevent the initial connection.

Federation Limitations and Security Filters

Instance administrators can configure ALLOWED_DOMAIN_BLOCKS and BLACKLISTED_DOMAIN_BLOCKS in the environment settings. If a remote domain is blocked at the instance level, all handle resolution attempts to that domain will fail. Additionally, the MEDIA_CACHE_BASE_URL setting, if misconfigured, can cause WebFinger requests to be routed incorrectly through a CDN that does not forward the request to the correct origin server.

Steps to Resolve the Handle Error

Follow these steps in order. Test the handle after each step to see if the error is resolved.

1. Verify the handle format
   Ensure the handle is typed exactly as @username@domain.tld with no leading or trailing spaces. Do not include the https:// prefix. Example: @gargron@mastodon.social. If you are unsure of the exact username, visit the user’s profile page on their instance and copy the handle from the URL or the profile header.
2. Check if the remote instance is online
   Open a web browser and navigate to the remote instance’s homepage (e.g., https://mastodon.social). If the page loads, the instance is online. If it does not load, the instance may be down for maintenance or permanently closed. Use a website monitoring tool like DownForEveryoneOrJustMe to confirm the status.
3. Test the WebFinger endpoint directly
   Open a new browser tab and enter the following URL, replacing user and remoteinstance.com with the actual values:
   https://remoteinstance.com/.well-known/webfinger?resource=acct:user@remoteinstance.com
   If the endpoint returns a JSON response with a subject field, the remote server is working. If it returns a 404 error, the user does not exist or the instance does not support WebFinger. If it returns a 403 or 410 error, the instance is blocking the request.
4. Use the profile URL as an alternative search
   In the Mastodon search box, paste the full profile URL of the user, such as https://remoteinstance.com/@user. Mastodon will attempt to fetch the ActivityPub actor object directly from that URL, bypassing the handle parsing step. If the fetch succeeds, the user will appear in the search results and you can follow them.
5. Ask the remote user to send you a direct message or mention
   If you have any other way to contact the user (email, another social platform), ask them to send a public mention or direct message to your Mastodon handle. Their instance will push the message to your instance via ActivityPub, which creates a local copy of the user’s profile. After the message arrives, the handle will resolve automatically.
6. Restart the Mastodon sidekiq and web processes (admin only)
   If you are the instance administrator, SSH into your server and run:
   systemctl restart mastodon-sidekiq mastodon-web
   This clears any stale connection caches and reinitializes the HTTP client pool. After restarting, try the handle search again.
7. Review the instance domain block list (admin only)
   Log in to the Mastodon admin interface. Navigate to Administration > Server Settings > Federation > Domain Blocks. Check if the remote instance domain is listed. If it is blocked, remove the block or change the severity to “None.” Save changes and retry the handle resolution.
8. Flush the DNS cache on the Mastodon server (admin only)
   On the server, run:
   systemd-resolve --flush-caches (if using systemd-resolved) or service nscd restart (if using nscd). This clears any stale DNS records that may be pointing to the wrong IP address for the remote instance.

If Mastodon Still Fails to Resolve the Handle

Handle resolves on one instance but not on another

This indicates a federation issue specific to your instance rather than a global problem. Check if your instance is in limited federation mode or has a whitelist enabled. If WHITELIST_MODE=true is set in the environment, your instance will only federate with instances explicitly added to a whitelist. Remove the whitelist or add the remote instance to it.

WebFinger endpoint returns a 410 Gone status

A 410 status means the user account has been deleted or moved to another instance. Mastodon returns “Failed to resolve handle” because the remote server explicitly states the resource is no longer available. In this case, you cannot follow that handle. Search for the user’s new handle or profile URL on the new instance.

Remote instance uses a non-standard port or HTTPS certificate

Some instances run on custom ports (e.g., 8443) or use self-signed certificates. Mastodon’s HTTP client rejects connections that do not have a valid TLS certificate. If you control the remote instance, install a valid certificate from Let’s Encrypt. If you do not, contact the instance administrator to fix the certificate.

Mastodon Handle Resolution: WebFinger vs Direct URL Search

Item	WebFinger Lookup	Direct URL Search
Request type	GET /.well-known/webfinger?resource=acct:user@domain	GET /@user or GET /users/user with Accept: application/activity+json
Dependency on remote server	Requires WebFinger endpoint to be reachable and returning valid JSON	Requires the remote web server to serve the ActivityPub actor object
Handle format required	Full handle with @user@domain	Full profile URL (https://domain/@user) or any URL that redirects to the actor JSON
Common failure reasons	Remote instance offline, domain blocked, DNS failure, incorrect handle syntax	Remote instance offline, profile URL changed, CORS policy blocking fetch
Success rate when remote is working	High for standard Mastodon instances	High for any ActivityPub-compatible software

After resolving the handle error, you can follow the user and see their posts in your home timeline. If you are an instance administrator, consider enabling the DIRECT_FETCH_ENABLED environment variable, which forces Mastodon to always try a direct URL fetch before falling back to WebFinger. This reduces resolution failures for instances with nonstandard WebFinger implementations.