Mastodon Migration Across Federation Modes: Allowlist Source Instance

When you move a Mastodon account from one instance to another, the migration process relies on a handshake between the old server and the new server. If your source instance uses a restrictive federation mode such as an allowlist or a limited federation policy, that handshake can fail silently. The new instance cannot pull your old profile data or send the migration request, leaving followers stuck and your old profile still active. This article explains why allowlist-based instances block migration requests and how to prepare your source instance so the migration completes successfully.

Why Allowlist Federation Blocks Account Migration

Mastodon instances can operate in three federation modes: open federation, limited federation, and allowlist-only federation. In allowlist mode, the instance only accepts incoming federated traffic from domains that an admin has explicitly approved. This includes ActivityPub messages, profile lookups, and migration requests.

When you initiate an account migration from an allowlist source instance, the following sequence occurs:

1. You enter the target instance’s domain and your new account name in the source instance’s Preferences > Account > Move to a different account form.
2. The source instance sends an ActivityPub Move activity to the target instance.
3. The target instance tries to verify the Move activity by fetching the source profile from the source instance.
4. If the source instance uses an allowlist and the target instance’s domain is not on that list, the fetch request is rejected. The target instance never receives the source profile data, so the migration cannot proceed.

The same problem occurs in reverse when the target instance also uses an allowlist. The source instance cannot send the Move activity to a domain that is not approved. In both cases, the migration appears to complete on the source side but the target instance never registers the move, and followers are not redirected.

Steps to Migrate From an Allowlist Source Instance

To migrate successfully, you must add the target instance’s domain to the source instance’s allowlist before starting the migration. You need admin access to the source instance. If you do not have admin rights, contact the instance administrator and provide the target instance’s domain.

Step 1: Identify the Target Instance Domain

1. Open your target instance
   Log in to the Mastodon instance where you created your new account. Look at the URL in your browser address bar. The domain is everything after https:// and before the first slash. For example, if the URL is https://mastodon.example/@username, the domain is mastodon.example.
2. Write down the exact domain
   Include any subdomains. Do not include www unless it appears in the URL. This domain is what you will add to the allowlist.

Step 2: Add the Target Domain to the Source Instance Allowlist

1. Log in to the source instance admin panel
   Use an account with admin privileges on the source instance. Go to Preferences > Administration > Federation.
2. Open the Allowlist management section
   Click the Allowlist tab. If you do not see this tab, the instance does not use allowlist mode. Contact your admin to check the federation policy.
3. Add the target domain
   Click Add domain. In the domain field, enter the exact domain from Step 1. Do not include https:// or a trailing slash. Click Add to save.
4. Wait for the change to propagate
   Mastodon caches federation rules. Wait 5 to 10 minutes before proceeding. You can also restart the Mastodon streaming and sidekiq processes to force a refresh, but a short wait is usually sufficient.

Step 3: Initiate the Migration on the Source Instance

1. Go to Preferences > Account
   On the source instance, click Preferences in the top menu, then select Account from the sidebar.
2. Scroll to the Move to a different account section
   Click Move to a different account.
3. Enter the target account details
   In the New account handle field, type @username@targetdomain using the username and domain from your new account. In the Current password field, enter your source instance password.
4. Click Move followers
   Mastodon sends the Move activity to the target instance. Because the target domain is now on the allowlist, the target instance can fetch the source profile and complete the verification.

Step 4: Confirm the Migration on the Target Instance

1. Log in to the target instance
   Switch to your new account on the target instance.
2. Go to Preferences > Account > Move from a different account
   Click Move from a different account.
3. Enter the source account details
   In the Old account handle field, type @username@sourcedomain. In the Current password field, enter your target instance password.
4. Click Confirm move
   The target instance verifies the Move activity from the source instance. If the source instance still blocks the target, this step fails. If the allowlist is in place, the verification succeeds and the migration is complete.

If the Migration Still Fails After Adding the Allowlist

Target Instance Also Uses an Allowlist

If the target instance also restricts federation to an allowlist, the source instance cannot send the Move activity to it. You must add the source instance’s domain to the target instance’s allowlist as well. Follow the same steps in Step 2 but on the target instance admin panel. Add the source instance domain. Then retry the migration from Step 3.

Migration Request Times Out

If the source instance or target instance is behind a firewall or reverse proxy that delays ActivityPub traffic, the migration request may time out. Check the server logs on both instances for Net::OpenTimeout or Net::ReadTimeout errors. Adjust firewall rules to allow outbound and inbound traffic on port 443 for the domain you added to the allowlist.

Follower Migration Does Not Complete

After the Move activity succeeds, followers on third-party instances receive a redirect notice. If those third-party instances also use allowlists and have not approved either the source or target domain, followers will not see the redirect. The source profile remains active for those followers. To fix this, ask the third-party instance admins to add the target domain to their allowlist. This is a limitation of allowlist-based federation that cannot be resolved from the source or target instance alone.

Federation Modes: Migration Compatibility Comparison

Item	Open Federation	Allowlist Federation	Limited Federation
Migration handshake	Works automatically	Requires allowlist entry on both sides	Works if target is not blocked
Admin action needed	None	Add target domain to source allowlist	Verify target not on blocklist
Follower redirect to new instance	Works for all followers	Fails if follower instance blocks either domain	Fails if follower instance blocks either domain
Profile fetch from source	Allowed from any instance	Only from allowlisted instances	Allowed unless instance is blocked

After you have added the target domain to the source instance allowlist and confirmed the migration, you can safely delete the old source account. Keep the allowlist entry in place for at least 48 hours after migration to ensure all follower instances have time to process the redirect. If you remove the entry too early, third-party instances that have not yet fetched the Move activity will see the old profile as active and will not redirect followers to the new instance.