Mastodon Federation Webfinger Lookup Failing: Fix

When Mastodon cannot find a remote user by their full handle, federation breaks. You see errors like “User not found” or “Failed to fetch account” when searching for someone on another instance. This happens because Webfinger lookup, the protocol Mastodon uses to resolve a user’s address into a profile URL, is failing. This article explains the root causes of Webfinger lookup failures and provides step-by-step fixes for administrators and users.

Webfinger is a discovery protocol defined in RFC 7033. Mastodon sends an HTTPS request to the remote domain asking for information about a resource, usually an email-style address like user@example.com. If that request fails or returns incorrect data, the remote profile cannot be loaded.

You will learn how to diagnose Webfinger failures, fix common misconfigurations on your own instance, and understand what to check on the remote server. This guide covers both Mastodon server settings and DNS configurations that affect federation.

Why Mastodon Webfinger Lookup Fails

Webfinger works by sending a GET request to https://domain.com/.well-known/webfinger?resource=acct:user@domain.com. The server must return a JSON document containing a link to the user’s ActivityPub profile. If any step in this chain breaks, Mastodon cannot federate with that user.

The most common root causes are:

• Missing or misconfigured .well-known/webfinger endpoint on the remote server. The web server (nginx or Apache) may not route requests to Mastodon correctly.
• DNS resolution failure for the domain used in the user handle. If the handle is user@example.com but Mastodon lives at mastodon.example.com, the Webfinger request goes to example.com, which must either serve the Webfinger response or redirect to mastodon.example.com.
• SSL/TLS certificate mismatch. The certificate presented by the remote domain must match the hostname in the Webfinger request. A certificate for example.com does not cover example.com unless explicitly included.
• Firewall or reverse proxy blocking the .well-known path. Some security scanners block paths starting with a dot.
• Mastodon version mismatch. Very old Mastodon instances may not support the required Webfinger response format.

The Webfinger Request Flow

When you search for @user@remoteinstance.com, your Mastodon instance does the following:

1. Extract the domain
   Your instance parses the handle and extracts remoteinstance.com as the target domain.
2. Send Webfinger request
   Your instance sends a GET to https://remoteinstance.com/.well-known/webfinger?resource=acct:user@remoteinstance.com.
3. Parse the response
   If the response is HTTP 200 with a valid JSON body containing a self link with type="application/activity+json", your instance extracts the profile URL.
4. Fetch the profile
   Your instance then fetches the profile from the URL provided in the Webfinger response.

If step 2 or step 3 fails, you see the lookup failure.

How to Fix Webfinger Lookup Failures

The fix depends on whether you control the remote server, your own server, or neither. Below are the steps for each scenario.

If You Control the Remote Server That Cannot Be Found

This is the most common scenario: users from other instances cannot find your users by handle. Follow these steps to verify and fix your server.

1. Test Webfinger manually
   Open a terminal and run: curl -v "https://yourdomain.com/.well-known/webfinger?resource=acct:yourusername@yourdomain.com". Replace yourusername and yourdomain.com with actual values. Check if you get a 200 response with JSON.
2. Check nginx routing
   If you get a 404 or 403, your web server is not passing requests to Mastodon. In nginx, ensure you have a location block for /.well-known/webfinger that proxies to your Mastodon backend (usually http://localhost:3000). In Apache, ensure RewriteRule or ProxyPass is configured.
3. Verify SSL certificate
   Run: curl -vI https://yourdomain.com/.well-known/webfinger. Check that the certificate is valid and matches yourdomain.com exactly. If you use a wildcard certificate for yourdomain.com, it does not cover yourdomain.com unless the certificate explicitly includes the bare domain.
4. Check Mastodon logs
   On your Mastodon server, run: journalctl -u mastodon-sidekiq -n 50. Look for errors containing "Webfinger" or "webfinger". Common errors include "Failed to fetch resource" or "JSON parse error".
5. Restart Mastodon services
   After any configuration change, restart Mastodon: systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming.

If You Are the User Trying to Find a Remote User

Verify the handle format
Make sure you are using the full handle format @username@domain.com including the @ before the username. Mastodon requires the acct: prefix internally, but the search box expects the full handle.

1. Try the Webfinger URL manually
   In a browser, go to https://domain.com/.well-known/webfinger?resource=acct:username@domain.com. Replace domain.com and username. If you get a JSON response, the remote server is working. If you get a 404 or error, the remote server is misconfigured.
2. Check if the remote domain is a redirect
   Some instances use a subdomain like mastodon.domain.com but the handle uses domain.com. The remote server must have a redirect from https://domain.com/.well-known/webfinger to https://mastodon.domain.com/.well-known/webfinger. You can test this with: curl -v "https://domain.com/.well-known/webfinger?resource=acct:user@domain.com" and check for a 301 or 302 redirect.
3. Contact the remote instance admin
   If the Webfinger endpoint returns an error, send the admin a copy of the curl output. They can follow the steps in the previous section.

If You Cannot Reach Any Remote User

If all remote lookups fail, the problem is likely on your own instance.

1. Check your DNS
   Ensure your server can resolve external domains. Run: nslookup remoteinstance.com. If DNS fails, check your /etc/resolv.conf file.
2. Check outbound firewall rules
   Your Mastodon server must make outbound HTTPS connections to remote servers. Verify that port 443 is not blocked in your firewall.
3. Test with a known working instance
   Try searching for @gargron@mastodon.social (the Mastodon creator). If that fails, your instance has a general federation problem.
4. Restart Mastodon
   Restart all Mastodon services: systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming.

If Webfinger Still Fails After the Main Fix

Webfinger Returns HTTP 404 for All Users

This usually means the .well-known directory is not configured in nginx or Apache. On nginx, ensure you have:

location ~ ^/.well-known/webfinger {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

On Apache, use:

ProxyPass /.well-known/webfinger http://localhost:3000/.well-known/webfinger
ProxyPassReverse /.well-known/webfinger http://localhost:3000/.well-known/webfinger

Webfinger Returns JSON but Without a "self" Link

This indicates a corrupted or incomplete database entry for that user. On the remote server, run:

RAILS_ENV=production bin/tootctl accounts refresh <username>

Replace <username> with the actual username. This command regenerates the Webfinger response for that user.

Webfinger Returns HTTP 500

Check the Mastodon web log: journalctl -u mastodon-web -n 50. Common causes are database connection failures or missing gems. Run bundle install in the Mastodon directory and restart.

Mastodon Webfinger vs DNS-Based Federation

Item	Webfinger Lookup	DNS-Based Federation
Protocol	HTTPS GET to /.well-known/webfinger	SRV record query
Used for	Resolving user handles to profile URLs	Discovering Mastodon server endpoints (optional)
Required for federation	Yes	No
Error symptom	"User not found" or "Failed to fetch account"	No effect on basic lookups
Configuration location	Web server (nginx/Apache) + Mastodon	DNS zone file

Webfinger is mandatory for Mastodon federation. DNS SRV records are optional and only used for server-to-server communication optimization.

After applying the fixes above, your Mastodon instance should successfully resolve remote users via Webfinger. Test with a known working handle like @gargron@mastodon.social. If the lookup succeeds, federation is restored. For ongoing monitoring, set up a cron job that runs curl against your own Webfinger endpoint weekly and alerts you if the response code is not 200.