When you search for a user on Mastodon by their full handle, you may see the error message “Lookup Failed” instead of the profile results you expect. This happens because Mastodon searches across the federated network of instances, and the lookup request can fail due to connectivity problems, instance blocks, or incorrect handle formatting. This article explains why the lookup fails and provides step-by-step fixes you can apply from your Mastodon web interface or mobile app.
The error is not a permanent block. It usually resolves after checking the handle format, restarting the client, or verifying that the remote instance is reachable. You can also use alternative search methods to find the user without triggering the same error.
Follow the instructions below to eliminate the most common causes of the lookup failed error and restore your ability to find and follow users across the Mastodon network.
Key Takeaways: Fixing the Mastodon Lookup Failed Error
- User handle format @user@instance.example: Always include both the username and the full domain of the remote instance when searching.
- Search box in Mastodon web or mobile app: Enter the full handle and press Enter, then wait for the lookup to complete before clicking any result.
- Instance block or federation pause: Check if your instance has blocked the remote instance or if the remote instance is temporarily unavailable.
Why the Lookup Failed Error Appears on Mastodon
Mastodon uses a federated architecture where each instance is a separate server that communicates with others through the ActivityPub protocol. When you enter a full user handle like @username@example.social into the search box, your instance sends a request to the remote instance asking for that user’s profile data. The lookup failed error occurs when that request does not return a valid response within a reasonable time.
Common Technical Causes
The remote instance may be offline, overloaded, or blocking requests from your instance. Your own instance may also have a temporary network issue that prevents it from reaching the remote server. Additionally, if you type the handle incorrectly, Mastodon cannot resolve the user because the domain portion does not match any known server.
Instance Blocks and Moderation
Instance administrators often block or limit federation with certain servers. If your instance has a domain block against the remote user’s instance, the lookup will fail silently. You can check this by asking your instance admin or looking at the instance’s moderation page if you have access.
Steps to Fix the Lookup Failed Error on Mastodon
- Verify the user handle format
Make sure you are using the full handle in the format@username@domain.tld. For example,@gargron@mastodon.social. Do not use just@usernameorusername@domainwithout the leading @. Paste the handle into a text editor first to check for hidden spaces or special characters. - Perform a fresh search after clearing the search box
Click inside the Mastodon search box, delete any existing text, then type or paste the full handle again. Press Enter and wait at least 10 seconds. Do not click any autocomplete suggestions until the lookup completes. If you see the error, proceed to the next step. - Restart the Mastodon client or reload the web page
Close the Mastodon browser tab or mobile app completely. Reopen the app and log in again if needed. Repeat the search with the same handle. This clears any temporary client-side cache that may interfere with the lookup. - Test connectivity to the remote instance
Open a new browser tab and visit the remote instance’s public URL directly. Example: if the handle is@user@example.social, go tohttps://example.social. If the page loads, the instance is online. If it times out or shows an error, the remote server may be down or blocking your IP range. - Use the Mastodon web interface instead of a third-party app
Third-party Mastodon clients may have outdated APIs or different search behavior. Log in to your instance’s web interface using a desktop browser and repeat the search there. If the lookup succeeds on the web interface, the issue is with your app. - Ask your instance administrator to check federation logs
Instance admins can view server logs to see why a lookup failed. They can check if the remote instance is blocked, if the request timed out, or if the remote server returned an error. Contact your admin through the instance’s support channel and provide the exact handle you tried to search.
If Mastodon Still Shows Lookup Failed After the Main Fix
Searching for a user without the full handle fails every time
If you only type the username without the domain, Mastodon searches only your local instance. To find a remote user, you must always include the full handle. If you do not know the exact domain, try searching for a post from that user by searching for a unique phrase they published. If you find the post, click the user’s name to visit their profile and then follow them from there.
Lookup works for some instances but not others
This indicates that your instance has blocked or is not federating with specific remote instances. You can check your instance’s domain blocks by going to Preferences > Moderation > Domain Blocks if you are an admin. If you are a regular user, you cannot remove these blocks yourself. Contact your admin to request that they allow federation with the blocked instance.
Lookup fails only on mobile app but works on web
This is a known issue with some Mastodon mobile apps that cache search results or use outdated API endpoints. Force-close the app, clear its cache from the device settings, and reopen it. If the problem persists, use the web interface on your mobile browser as a temporary workaround.
| Item | Web Interface | Mobile App |
|---|---|---|
| Search behavior | Direct lookup using ActivityPub | May use cached or limited API |
| Cache clearing | Browser cache or incognito mode | App cache or reinstall |
| Handle requirement | Full @user@domain required | Same requirement |
The lookup failed error on Mastodon is almost always caused by a network or formatting issue that you can fix by following the steps above. After verifying the handle format and checking the remote instance’s availability, you should be able to search for and follow users across the fediverse without interruption. For persistent problems, always contact your instance administrator for server-side diagnosis.