How to Resolve Mastodon ‘Webfinger Lookup Failed’ Error

When you try to follow a user on another Mastodon instance or search for a remote account, you may see the error “Webfinger Lookup Failed.” This error means that your instance cannot verify that the remote user exists. The problem usually lies in a misconfigured domain, a missing DNS record, or a temporary server outage. This article explains what causes the Webfinger lookup to fail and provides step-by-step instructions to fix it.

Why Mastodon Shows the Webfinger Lookup Failed Error

Webfinger is a protocol that Mastodon uses to discover a user’s profile URL from their email-style address (for example, @user@example.com). When you search for a remote user, your instance sends a request to the remote domain’s Webfinger endpoint at https://example.com/.well-known/webfinger?resource=acct:user@example.com. The remote server must respond with JSON that includes the user’s profile URL and activity streams endpoint.

The error “Webfinger Lookup Failed” occurs when this request returns an HTTP error (404, 500, or timeout) or when the response is malformed. Common causes include:

• Missing or incorrect DNS records for the remote domain
• A reverse proxy (NGINX, Apache, Caddy) that does not forward the Webfinger path to the Mastodon backend
• Mastodon itself not running or misconfigured on the remote instance
• A firewall or CDN blocking the request

The fix depends on whether you are the administrator of the remote instance or a user trying to follow someone. This guide covers both scenarios.

Steps to Fix Webfinger Lookup Failed on Your Own Instance

If you run the Mastodon instance that is failing lookup, follow these steps to resolve the issue. If you are a user on a different instance, skip to the next section.

1. Check the Mastodon process status
   Log into your server via SSH. Run systemctl status mastodon-web to confirm the web process is active. If it is not running, start it with systemctl start mastodon-web.
2. Verify DNS records for your domain
   Use a tool like dig or an online DNS checker to confirm that your domain has an A record (or AAAA for IPv6) pointing to your server IP. Also check that webfinger.yourdomain.com resolves to the same IP. Some CDNs require a CNAME record for the subdomain.
3. Examine the reverse proxy configuration
   Open your NGINX or Apache config file. Look for the location block that handles the /.well-known/ path. It must include a proxy pass to the Mastodon backend (usually port 3000 or a Unix socket). Example NGINX block:

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

4. Test the Webfinger endpoint directly
   On the server, run curl -I https://yourdomain.com/.well-known/webfinger?resource=acct:admin@yourdomain.com. A successful response returns HTTP 200 with a Content-Type of application/jrd+json. If you see a 404 or 502, the proxy or Mastodon is misconfigured.
5. Review Mastodon environment variables
   Edit the .env.production file. Ensure LOCAL_DOMAIN is set to your public domain (e.g., example.com). Do not include https://. If you use a subdomain for Mastodon (e.g., social.example.com), set LOCAL_DOMAIN to that subdomain and also set WEB_DOMAIN if needed.
6. Restart Mastodon services
   After making changes, run systemctl restart mastodon-web and systemctl reload nginx (or Apache equivalent).

What to Do When Following a Remote User on Another Instance

If you are a regular user and see this error when trying to follow someone on a different Mastodon server, the problem is likely on the remote instance. However, there are a few things you can check on your side.

1. Confirm the user’s full address
   Make sure you have the correct handle in the format @username@domain. Typing a wrong domain is the most common cause. Check the user’s profile page for the exact string.
2. Search using the full URL instead
   In the Mastodon search bar, paste the user’s full profile URL (e.g., https://remoteinstance.com/@username). This bypasses Webfinger and uses the ActivityPub fetch directly.
3. Wait and retry later
   The remote instance may be experiencing a temporary outage or maintenance. Try again after 30 minutes. If the error persists, the instance may have a permanent configuration issue.
4. Contact the remote instance admin
   If you cannot reach the user any other way, find the admin contact email or Mastodon account for the remote instance and report the problem. Include the exact error message and the handle you tried to follow.

If Webfinger Lookup Still Fails After the Main Fix

Mastodon returns 500 Internal Server Error on Webfinger request

A 500 error means the Mastodon application itself is failing. Check the Mastodon logs with journalctl -u mastodon-web -n 50. Look for Ruby exceptions or database connection errors. Common causes include a full database connection pool or a missing gem. Restart the sidekiq service as well with systemctl restart mastodon-sidekiq.

CDN or firewall blocking the request

Cloudflare, CloudFront, or other CDNs may block requests to the /.well-known/ path if they are not configured to pass through. In Cloudflare, create a page rule that sets SSL to Full and ensures the path is not cached. For firewalls like iptables or UFW, verify that port 443 is open and that rate limiting does not block the remote instance’s IP.

Webfinger returns 404 for valid users

A 404 indicates that the Webfinger endpoint is not reachable or Mastodon cannot find the user. Double-check the DNS A record and the reverse proxy path. Also verify that the user account is not suspended or deleted. On the Mastodon server, run RAILS_ENV=production bin/tootctl accounts lookup username to confirm the account exists in the database.

Item	Correct Configuration	Incorrect Configuration
DNS A record	Points to server IP	Points to wrong IP or missing
Reverse proxy path	Includes /.well-known/ proxy pass	Missing or returns static files
LOCAL_DOMAIN env	Matches public domain exactly	Has extra subdomain or typo
Mastodon web process	Running and listening	Stopped or crashed

Once you have corrected the DNS records, proxy configuration, or environment variables, the Webfinger lookup should succeed. Test by searching for a remote user from another instance. If you are an administrator, also monitor the Mastodon logs for any recurring errors. As an advanced step, consider setting up a dedicated webfinger subdomain with a CNAME record to reduce load on your primary domain.