How to Fix Mastodon Error ‘Webfinger Lookup Failed’ for Mention

When you try to mention a user on another Mastodon instance by typing their full handle, you may see the error “Webfinger Lookup Failed.” This error prevents the mention from resolving and the post from being sent. The cause is usually a DNS or server configuration issue that stops Mastodon from finding the user’s account via Webfinger. This article explains why the error occurs and provides step-by-step fixes for both instance administrators and regular users.

Why the Webfinger Lookup Fails for Mentions

Webfinger is a protocol that Mastodon uses to translate a username@domain handle into an ActivityPub actor URL. When you type @user@example.com in a post, your instance sends an HTTP request to https://example.com/.well-known/webfinger?resource=acct:user@example.com. The target server must respond with a JSON object containing the user’s profile URL. If any part of this chain fails, Mastodon shows the lookup error.

Common failure points include:

• DNS records for the target domain are missing or incorrect.
• The target instance’s web server (Nginx or Apache) blocks the .well-known directory.
• The Mastodon service on the target instance is down or overloaded.
• A reverse proxy or CDN caches an old or empty response.
• The user account does not exist or has been moved or deleted.

Steps to Diagnose and Fix the Webfinger Lookup Failed Error

Follow these steps in order. Start with basic checks and escalate to server-side fixes if needed.

1. Verify the user handle is correct
   Check that you typed the handle exactly as @username@domain. The domain must match the user’s home instance. A typo in either part causes the lookup to fail immediately.
2. Test the Webfinger endpoint manually
   Open a browser or use curl to request https://domain/.well-known/webfinger?resource=acct:username@domain. Replace domain and username with the actual values. A successful response returns HTTP 200 and a JSON body with an subject field. If you get a 404 or an empty response, the issue is on the target server.
3. Check the DNS A record for the target domain
   Use a tool like nslookup domain or dig A domain from your server. The domain must resolve to an IP address that runs a Mastodon instance. If the DNS record is missing or points to a different server, the Webfinger request cannot reach the correct host.
4. Inspect the Nginx or Apache configuration on the target server
   On the target instance, verify that the web server allows access to the /.well-known/ path. For Nginx, ensure the location block for /.well-known/ is not restricted. Apache users should check that AllowOverride or RewriteRule does not block the directory.
5. Restart the Mastodon web service on the target instance
   If the target instance is under maintenance or overloaded, restart its web process. On a typical Mastodon setup, run systemctl restart mastodon-web or docker-compose restart web depending on the deployment. After restart, test the Webfinger endpoint again.
6. Clear the Webfinger cache on your own instance
   Your Mastodon instance caches Webfinger results to reduce load. If a previous lookup failed, the cached failure may block future attempts. Run RAILS_ENV=production bin/tootctl cache clear from the Mastodon directory on your server. This flushes all cached values, including Webfinger responses.
7. Check for CDN or reverse proxy caching
   If the target instance uses Cloudflare, Fastly, or another CDN, the CDN may cache a 404 response. Purge the cache for the specific URL /.well-known/webfinger. On Cloudflare, use the Purge Cache option under the Caching tab. Wait a few minutes and test again.
8. Verify the user account is active and not moved
   Log into the target instance as an admin and check the user’s account status. If the user has moved their account to another instance using the Move feature, their old handle returns a 410 Gone response. You must use the new handle instead.

If the Webfinger Lookup Still Fails After the Main Fix

Webfinger returns HTTP 500 from the target instance

A server error indicates a problem with the Mastodon application on the target instance. Check the Mastodon logs with journalctl -u mastodon-web -n 50 or review the log/production.log file. Common causes include database connection failures, missing dependencies, or a corrupted user record. Restarting the Mastodon sidekiq process with systemctl restart mastodon-sidekiq often resolves transient errors.

Webfinger returns HTTP 301 or 302 redirect

A redirect means the target server is configured to forward the request to a different URL. Mastodon follows redirects by default, but if the redirect chain leads to a non-Mastodon server or a domain that does not serve Webfinger, the lookup fails. Check the redirect target by inspecting the Location header in the response. If the redirect points to a different domain, update the user’s handle to match the final domain.

Webfinger works from one instance but not another

If you can resolve a user from your desktop browser but not from your Mastodon instance, the issue is likely DNS resolution on your server. Your instance’s DNS resolver may not have the correct records. Edit /etc/resolv.conf on your server to use a public DNS resolver like 8.8.8.8 or 1.1.1.1. After changing the resolver, restart the Mastodon web service and clear the cache again.

Item	Local Fix (Your Instance)	Remote Fix (Target Instance)
Cause of error	Cached failed lookup or DNS misconfiguration on your server	Missing DNS A record, blocked .well-known path, or down Mastodon service
Primary fix	Clear cache with bin/tootctl cache clear	Fix DNS A record or unblock .well-known in web server config
Verification tool	curl to your own instance’s Webfinger endpoint	curl directly to the target domain’s Webfinger endpoint
Time to apply	Under 1 minute	5 to 30 minutes depending on DNS propagation

After completing the fixes, test the mention again by typing @user@domain in a new post. The mention should resolve to the user’s display name and profile link. If the error persists, repeat the steps with extra attention to the web server configuration on the target instance. You can also ask the target instance administrator to run RAILS_ENV=production bin/tootctl accounts refresh [username] to force a user account refresh.