Mastodon Alias Setup Missing on Old Account: Fix

When you try to move your followers from an old Mastodon account to a new one, the required Alias setup option sometimes does not appear in the old account’s settings. This missing option prevents the follower migration handshake from starting. The cause is usually a difference in Mastodon software versions or a disabled migration feature on the old instance. This article explains why the Alias setup option can be missing and provides the exact steps to fix it so you can complete your account migration.

Why the Alias Setup Option Is Missing on Your Old Mastodon Account

Mastodon account migration uses a two-step handshake. First, you set an alias on the old account that points to the new account. Second, you use the Move followers option on the new account to pull followers from the old account. If the Alias option is missing on the old account, the handshake cannot begin.

The most common root cause is that the old Mastodon instance runs a software version older than 3.5.0. The Alias feature was introduced in Mastodon v3.5.0. Instances running older versions do not have this setting at all. Another cause is that the instance administrator has disabled the account migration feature through the admin panel. Some instances restrict migration to prevent spam or abuse.

A third cause is a browser caching issue. After your instance updates to a version that supports aliases, your browser may still show the old interface without the Alias option. Clearing the browser cache for the instance domain resolves this.

Steps to Fix the Missing Alias Setup on the Old Account

Follow these steps in order. After each step, check whether the Alias option appears under Preferences > Account on the old account.

1. Check the Mastodon version of the old instance
   Open the old instance in a browser. Scroll to the footer of any page. Look for the version number, such as v4.0.2 or v3.4.1. If the version is below 3.5.0, the Alias option does not exist in that software. You must contact the instance admin and ask them to update Mastodon to at least v3.5.0.
2. Clear browser cache and cookies for the old instance domain
   In Chrome or Edge, click the lock icon next to the URL. Select Cookies and site data > Manage cookies and site data. Delete all cookies for the instance domain. Then press Ctrl+F5 to force a full page reload. In Firefox, click the lock icon, then Clear cookies and site data. Reload the page and navigate to Preferences > Account. The Alias option may now appear.
3. Try a different browser or incognito mode
   Open the old instance in a private browsing window. Log in to your old account. Go to Preferences > Account. If the Alias option appears, the issue is browser cache. Use the cleared browser or switch to the private window for the migration steps.
4. Check for instance-level feature flags
   If the Alias option still does not appear, the instance admin may have disabled account migration. Send a direct message or email to the admin. Ask: Is the account migration feature enabled on this instance? If not, request that they enable it. The admin can check in the admin dashboard under Server settings > Features.
5. Use the API as a temporary workaround
   If the admin cannot update the instance or enable the feature, you can set the alias via the Mastodon API. Open a browser and go to: https://oldinstance.example.com/api/v1/accounts/update_credentials. Replace the URL with your actual instance domain. Log in if prompted. In the JSON editor, add this field: “alias”: “https://newinstance.example.com/@yournewusername”. Replace the values with your new account URL. Click Submit. This bypasses the missing UI and directly sets the alias. Then proceed with the Move followers step on the new account.

If the Alias Still Does Not Appear After These Steps

Alias setup still missing after updating Mastodon version

If the instance updated to v3.5.0 or later but the Alias option remains hidden, the admin may need to run database migrations. Ask the admin to run: RAILS_ENV=production bin/rails db:migrate from the server terminal. This applies any pending database schema changes that enable the Alias feature.

Error when setting alias via the API

If the API returns a 422 error, the alias format is incorrect. Ensure the alias value is the full URL of your new Mastodon profile, including https:// and the instance domain. Example: https://newinstance.social/@yourname. Do not include a trailing slash.

Move followers option missing on the new account

After setting the alias on the old account, go to the new account. Open Preferences > Account > Move from a different account. If this option is missing, the new instance may also be outdated or have migration disabled. Apply the same version check and admin contact steps for the new instance.

Mastodon Account Migration: Old Instance vs New Instance Requirements

Item	Old Instance	New Instance
Required Mastodon version	v3.5.0 or later	v3.5.0 or later
Required setting	Alias (set on old account)	Move from a different account (used on new account)
Feature flag needed	Account migration enabled by admin	Account migration enabled by admin
Browser requirement	Fresh cache or private window	Fresh cache or private window
API fallback available	Yes, via update_credentials endpoint	Yes, via update_credentials endpoint for Move

Setting the alias on the old account is the first step. The Move followers option on the new account pulls the followers. Both instances must meet the version and feature flag requirements.

After you have set the alias using one of the methods above, proceed to the new account. Open Preferences > Account > Move from a different account. Enter the old account username and instance domain. Confirm the action. Followers from the old account will begin migrating to the new account over the next few minutes. If you used the API workaround, the Move step works the same way because the alias is already stored on the old account server. The missing Alias setup is now fixed and the migration can complete.