Mastodon ‘Could Not Find User’ on a Valid Handle: Fix

When you type a valid Mastodon handle like @user@instance.social into the search bar and see the error Could not find user, the account is real but your instance cannot reach it. This error appears even when the handle is spelled correctly and the account exists on another server. The cause is almost always a federation block, a temporary network timeout, or a missing WebFinger record on the remote instance. This article explains why the error occurs and provides step-by-step fixes to resolve it from both the user and the instance admin side.

Why Mastodon Cannot Find a Valid User Handle

Mastodon uses the WebFinger protocol to resolve a handle like @user@example.social into an actual account URL. When you search for a handle, your instance sends a request to https://example.social/.well-known/webfinger?resource=acct:user@example.social. The remote server must return a JSON response containing the account’s ActivityPub actor ID. If any step in this chain fails, Mastodon shows the Could not find user error.

The most common causes are:

• Federation block on your instance: Your admin has added the remote domain to a block list, preventing any communication.
• Remote server overload or timeout: The remote instance may be under load or temporarily unreachable, causing the WebFinger request to time out.
• Missing or malformed WebFinger response: The remote server may not support WebFinger, may have a misconfigured reverse proxy, or may return an HTTP error (404, 500).
• Search scope limitation: Mastodon by default only searches local users and cached remote users. Handles for uncached remote accounts may not resolve unless you enable full network search.
• Handle format error: The handle must use the full format @username@domain. Omitting the domain or using the wrong domain prefix causes the lookup to fail.

Steps to Fix the Could Not Find User Error

Follow these steps in order. Each step resolves a specific cause of the error. If one step does not fix the problem, proceed to the next.

1. Enable search across the entire known network
   Go to Preferences > Search. Turn on the toggle labeled Search entire known network. This tells your instance to actively query remote servers for handles it has not cached yet. After enabling it, try the search again. If the handle resolves, the issue was the default local-only search scope.
2. Verify the handle format and domain
   Confirm the handle uses the exact format @username@domain.tld. For example, @gargron@mastodon.social. Do not include extra spaces or characters. Check the domain spelling — a typo like mastodon.socia instead of mastodon.social will cause the error. If the account is on a custom domain, ensure the domain serves Mastodon or a compatible ActivityPub server.
3. Test the WebFinger endpoint manually
   Open a new browser tab and enter: https://domain.tld/.well-known/webfinger?resource=acct:username@domain.tld. Replace domain.tld and username with the remote account details. If the page returns a JSON object with a subject field, the WebFinger endpoint works. If the page shows a 404, 500, or blank response, the remote instance has a configuration problem that only its admin can fix.
4. Check your instance’s federation block list
   If you are the instance admin, go to Administration > Federation > Domain blocks. Look for the remote domain in the list. If it appears with a severity of Suspend or Silence, your instance will not fetch any data from that server. Remove the block or change the severity to None to allow the lookup. If you are not an admin, contact your instance admin and ask them to check the domain block list.
5. Use the remote user’s full profile URL instead of the handle
   Instead of searching by handle, paste the full profile URL of the remote user into your Mastodon search bar. For example: https://mastodon.social/@gargron. Mastodon can often resolve the account from the URL even when the handle lookup fails, because the URL directly references the user’s ActivityPub actor ID.
6. Wait and retry after server load subsides
   If the remote instance is experiencing high traffic or a temporary outage, the WebFinger request may time out. Wait 15 to 30 minutes and try the search again. You can check the remote instance’s status using a service like updown.io to confirm it is online.

If Mastodon Still Cannot Find the User After the Main Fix

User handle resolves on one instance but not another

This indicates a federation block or configuration difference between instances. Ask the admin of the instance where the lookup fails to check their domain block list and their Authorized Fetch setting. If Authorized Fetch is enabled, some remote servers may reject the request if your instance is not on their allow list.

WebFinger returns a 404 error for a valid account

The remote instance may be running a software version that does not support WebFinger or has a misconfigured reverse proxy (nginx, Apache, Caddy). The remote admin must verify that their server serves /.well-known/webfinger and that the path is not blocked by a firewall or proxy rule. The admin can test the endpoint using curl -i https://domain.tld/.well-known/webfinger?resource=acct:user@domain.tld from the command line.

Search entire known network toggle does not appear

The Search entire known network option is only available on Mastodon version 3.5.0 and later. If you are on an older version, the toggle does not exist. Update your Mastodon instance to the latest stable release to gain this feature. If you are on a managed instance (mastodon.social, mastodon.online), the admin controls the version and must perform the update.

Item	Handle Search With Full Network Toggle Off	Handle Search With Full Network Toggle On
Search scope	Local users and cached remote users only	All known federated instances via WebFinger
Lookup speed	Instant for cached handles	May take 3–10 seconds depending on remote server response
Requires WebFinger on remote	No, only cached data	Yes, remote must serve valid WebFinger
Works on blocked domains	No	No

This table shows that the full network search toggle expands the lookup scope but does not bypass federation blocks or missing WebFinger endpoints. Both options fail if the remote server is blocked or misconfigured.

After following the steps above, you can now resolve the Could not find user error by enabling network-wide search, verifying the WebFinger endpoint, and checking federation blocks. If the issue persists, provide your instance admin with the exact error message and the remote handle. The admin can check the server logs for WebFinger request failures. As an advanced tip, admins can test federation health by using the tootctl accounts caches command to inspect cached remote accounts and force a refresh of a specific user’s data.