When you migrate your Mastodon account from one instance to another, the new instance must verify your old account through Webfinger. This verification step confirms you control the old account before followers are transferred. Without successful verification, the migration process fails, leaving your followers stranded on the old instance. This article explains why Webfinger verification fails and provides step-by-step fixes to resolve the issue.
Key Takeaways: Fixing Webfinger Verification During Mastodon Migration
- Preferences > Account > Move from a different account: Initiates the Webfinger verification handshake between the old and new Mastodon instances.
- Old instance account settings > Account > Move to a different account: Generates the migration alias and redirect code that Webfinger checks.
- DNS TXT record for webfinger domain: Required when the old instance uses a custom domain to ensure Webfinger resolution works correctly.
Why Webfinger Verification Fails During Mastodon Migration
Webfinger is a protocol that allows Mastodon instances to look up information about a user by their email-style address (username@instance.com). During account migration, the new instance sends a Webfinger request to the old instance to confirm that the old account exists and belongs to the person initiating the migration. If the old instance is unreachable, returns an error, or does not recognize the alias, the verification fails.
The root causes typically fall into three categories:
Instance Unreachability or DNS Resolution Failure
If the old instance has been shut down, is behind a firewall, or its domain name no longer resolves to the correct IP address, the new instance cannot send the Webfinger request. This is common when migrating away from a small or poorly maintained instance that has gone offline.
Missing or Incorrect Alias Configuration on the Old Instance
The migration process requires you to set an account alias on the old instance. This alias tells the old instance that your account has moved to the new address. Without this alias, the Webfinger response from the old instance will not include the redirect information, causing verification to fail.
Webfinger Endpoint Not Responding Correctly
Some Mastodon instances have custom configurations or third-party reverse proxies that block or modify Webfinger requests. If the endpoint /.well-known/webfinger is not accessible, returns a 404, or serves incorrect JSON, the new instance cannot complete the verification.
Steps to Fix Webfinger Verification During Account Migration
Follow these steps in order. Do not skip any step, as each builds on the previous one.
- Verify the old instance is still online
Open a browser and navigate to the old instance’s homepage. If the page loads, the instance is reachable. If it returns a 502 or 503 error, the instance may be temporarily down. Wait 24 hours and try again. If the domain shows a DNS error or the page is blank, the instance is likely permanently offline. In that case, you cannot perform a standard migration and must contact the old instance admin or use alternative methods to notify your followers manually. - Set the account alias on the old instance
Log in to your old Mastodon account. Go to Preferences > Account > Move from a different account. Actually, the alias setting is under Preferences > Account > Account settings > Move to a different account. Enter the full address of your new account (username@newinstance.com). Save the changes. This creates a Webfinger-compatible alias that points to your new account. - Initiate the migration on the new instance
Log in to your new Mastodon account. Go to Preferences > Account > Move from a different account. Enter the full address of your old account (username@oldinstance.com). The new instance will send a Webfinger request to the old instance. If the alias is set correctly and the old instance is reachable, you will see a confirmation message. Click the confirmation button to proceed. - Check Webfinger resolution manually
If the migration fails, test the Webfinger endpoint manually. Open a browser and visithttps://oldinstance.com/.well-known/webfinger?resource=acct:username@oldinstance.com. Replaceoldinstance.comandusernamewith the actual domain and username. The response should be a JSON object containing asubjectfield and alinksarray with an alias pointing to your new account. If you see a 404 or an empty JSON, the alias is not set correctly. Return to step 2 and verify the alias. - Configure DNS if using a custom domain
If your old instance uses a custom domain (not the default instance domain), you must add a DNS TXT record to verify domain ownership. Log in to your domain registrar’s control panel. Add a TXT record for_mastodonwith valueoldinstance.com. Wait for DNS propagation, which can take up to 48 hours. Then retry the migration from the new instance. - Contact the old instance admin if problems persist
If the Webfinger endpoint returns an error or the instance is unreachable but not permanently offline, contact the instance admin. Ask them to check the server logs for Webfinger requests and ensure the reverse proxy (if any) is not blocking/.well-known/webfinger. The admin can also manually trigger a Webfinger cache refresh by restarting the Mastodon web service.
If Webfinger Still Fails After the Main Fix
Webfinger Request Times Out
A timeout indicates the old instance is reachable but not responding quickly enough. This often happens with overloaded instances. Wait 30 minutes and retry. If the timeout persists, the instance may be rate-limiting Webfinger requests. Use the manual Webfinger test from step 4 to confirm the endpoint is working. If the manual test succeeds but the migration times out, ask the old instance admin to temporarily disable rate limiting for your account.
Webfinger Returns a 404 Error
A 404 error means the Webfinger endpoint does not exist or the resource is not found. Verify that the URL in step 4 uses the correct format. If the endpoint returns 404 for all accounts, the instance may have disabled Webfinger or uses a nonstandard path. Contact the admin to enable the standard Webfinger endpoint at /.well-known/webfinger.
Migration Succeeds But Followers Do Not Transfer
Even if Webfinger verification passes, follower migration may not complete immediately. Mastodon queues follower transfers and processes them in batches. Wait up to 24 hours. If no followers appear, check your old account’s followers list. If followers are still there, the migration may not have been fully processed. Retry the migration from the new instance. If the problem continues, the old instance may have a bug in its migration handler. Report the issue to the admin with the exact error message from the server logs.
| Item | Webfinger Verification Success | Webfinger Verification Failure |
|---|---|---|
| Old instance status | Online and accessible | Offline, DNS error, or rate-limited |
| Alias configuration | Set correctly on old instance | Missing or incorrect alias |
| Webfinger endpoint | Returns valid JSON with alias | Returns 404, timeout, or incorrect data |
| DNS setup for custom domain | TXT record added and propagated | Missing TXT record |
You can now diagnose and fix Webfinger verification failures during Mastodon account migration. Start by checking the old instance is online and the alias is set. If manual Webfinger tests fail, contact the instance admin. For persistent issues, verify DNS records for custom domains. This approach resolves the vast majority of migration verification problems.