When you move your Mastodon account from one instance to another, your followers may not automatically know where you went. Without a proper alias, the old instance cannot redirect follower requests or notify followers of the move. This article explains how to create an account alias, which is the first step in a standard Mastodon migration. You will learn the exact settings to configure on both your old and new accounts.
Key Takeaways: Setting Up an Alias for Mastodon Account Migration
- Preferences > Account > Move from a different account: Initiates the alias handshake between your old and new Mastodon accounts.
- Old account profile URL: You must enter the full URL of your old account, including the instance domain, in the new account’s alias field.
- Old account password: The alias verification process requires you to re-enter the password for your old account on the new instance.
What an Account Alias Does During Mastodon Migration
An account alias is a declaration stored on your new Mastodon instance that points back to your old account. When you later run the official Move followers process, the new instance uses this alias to signal the old instance to redirect follower requests. Without the alias, the old instance rejects the redirect request because it cannot verify that the new account belongs to you.
The alias is not a public profile field. It is an internal setting visible only to the instance administrators and the migration system. Mastodon uses the alias to perform a cryptographic handshake between the two instances. This handshake confirms that the same person controls both accounts before any follower data is transferred.
You must create the alias on the new account before you start the Move process. The order matters. If you set the alias after initiating the move, the migration may fail silently or produce an error. The alias remains active even after the migration completes, which allows followers to continue redirecting to your new account if they attempt to follow the old account later.
Steps to Create an Account Alias Between Two Mastodon Instances
Follow these steps exactly in the order shown. You will need access to both your old account and your new account. Keep the old account logged in on one browser tab and the new account on another tab.
- Log in to your new Mastodon account
Open the instance where you created the new account. Enter your email and password. If you have not yet created the new account, register on the target instance and set up your profile first. - Navigate to Preferences > Account
Click the Preferences link in the right sidebar or the gear icon on the web interface. On the Account settings page, scroll down until you see the section labeled Moving from a different account. - Enter the old account URL
In the text field labeled Old account, type the full URL of your old Mastodon profile. The URL must include the instance domain. Example: https://mastodon.social/@yourusername. Do not use a shortened link or a profile alias. The URL must point to the actual account page on the old instance. - Enter the old account password
Below the URL field, you will see a password prompt. Type the password for your old Mastodon account. This is required to prove that you control the old account. The new instance sends this password securely to the old instance for verification. Mastodon does not store the password on the new instance. - Click the Save button
After entering both the URL and the password, click Save. The new instance contacts the old instance to verify the alias. If successful, you will see a green confirmation message at the top of the page. If the verification fails, check that the old account URL is correct and that the old account is still active. - Verify the alias status
Return to the Preferences > Account page. The Moving from a different account section now shows the old account URL and a status message indicating that the alias is active. If you do not see the alias listed, repeat steps 2 through 5.
If the Alias Verification Fails
The most common reason for alias failure is an incorrect old account URL. Copy the URL directly from your old profile page in a separate browser tab. Do not type the URL manually. Another common cause is that the old account has been deleted or suspended. The alias process requires the old account to exist and be accessible over the internet. If the old instance is down, wait until it is online before retrying.
Common Mistakes and Limitations When Creating an Account Alias
Alias Not Showing After Saving
If you save the alias details but the page does not display the alias, your Mastodon instance may be running an older version. The alias feature was introduced in Mastodon version 3.5.0. Check the instance version by looking at the footer of the web interface. If the version is earlier than 3.5.0, ask the instance administrator to upgrade.
Attempting to Create an Alias on the Old Account Instead of the New One
The alias must be created on the new account, not the old one. The old account does not have a setting to declare a new alias. The old account only has a Move to a different account option, which is the second step of the migration. If you enter the new account URL on the old account, the migration will not work correctly because the alias handshake was never established.
Alias Expiration or Removal After Migration
The alias remains active indefinitely unless you manually remove it. To remove the alias, go to Preferences > Account on the new account and click the Remove alias button. Removing the alias does not affect followers who have already moved. However, any new follow requests sent to the old account after the alias is removed will not be redirected.
Multiple Aliases for One Account
Mastodon allows only one alias per account. If you have migrated multiple times, only the most recent alias is active. If you need to move to a third instance, you must first remove the existing alias on your current new account, then create a new alias pointing to the previous account. This ensures the chain of ownership remains clear to the federation system.
Account Alias vs Move Process: What Each Step Handles
| Item | Account Alias | Move Process |
|---|---|---|
| Purpose | Verifies ownership between old and new accounts | Redirects followers and posts to the new account |
| Where configured | On the new account | On the old account |
| Data transferred | None | Follower list and optional bio |
| Requires password | Yes, old account password | Yes, old account password |
| Visible to others | No, internal only | Yes, old profile shows a redirect notice |
The alias is a prerequisite for the Move process. If you skip the alias, the Move process will fail because the old instance cannot verify that the new account belongs to you. Always create the alias first, then run the Move process on the old account.
You can now create an account alias between any two Mastodon instances that run version 3.5.0 or later. After the alias is active, proceed to the old account and use the Move to a different account option to transfer your followers. For a smoother transition, set your new profile bio to mention the migration so visitors see your new location immediately.