Mastodon Account Migration With Custom Domain Handle: Setup

You have a Mastodon account on one instance and want to move to a new instance while keeping your custom domain handle. Mastodon supports account migration, but using a custom domain handle adds extra DNS and configuration steps. This article explains how to set up a custom domain handle on your new Mastodon instance and migrate your followers, posts, and profile data from your old account. You will learn the exact DNS records to add, the migration process, and how to verify everything works correctly.

What Is a Custom Domain Handle in Mastodon and Why You Need DNS Setup

A custom domain handle lets you use your own domain name as part of your Mastodon identity. Instead of @username@mastodon.social, you can have @username@yourdomain.com. This is useful for individuals and businesses who want a consistent online identity across platforms.

To use a custom domain handle, your Mastodon instance must support it. Most self-hosted instances allow this, but managed instances may not. The core requirement is that your custom domain must point to the Mastodon instance server via DNS. Mastodon uses the domain to verify that you control the custom domain before allowing the handle to appear in your profile.

The DNS setup involves creating a CNAME record that maps your custom domain to the instance server hostname. This record tells Mastodon and other federated servers that the custom domain belongs to your instance. Without this record, the handle will not resolve and migration will fail.

Prerequisites for Custom Domain Handle Migration

Before starting, confirm you have the following:

• An existing Mastodon account on any instance (the old account).
• A new Mastodon account on a different instance (the new account) that supports custom domain handles.
• Access to your domain registrar or DNS hosting provider to add DNS records.
• Administrative access to the new Mastodon instance, or the ability to request the instance admin to add your custom domain to the allowed aliases list.

Steps to Set Up Custom Domain Handle and Migrate Your Mastodon Account

The process has three phases: DNS configuration, instance alias setup, and the migration handshake.

Phase 1: Configure DNS for Your Custom Domain Handle

1. Log in to your DNS provider
   Go to your domain registrar or DNS hosting provider control panel. Common providers include Namecheap, Cloudflare, GoDaddy, or Google Domains.
2. Create a CNAME record for the custom domain
   Add a new CNAME record with the following values:
   – Name: @ (or your domain root)
   – Target: the hostname of your new Mastodon instance (for example, mastodon.yourinstance.com)
   – TTL: 3600 (or leave default)
   This record tells servers that your custom domain is an alias for your instance server.
3. Wait for DNS propagation
   DNS changes can take from a few minutes to 48 hours. Use a tool like whatsmydns.net to check when the CNAME record is visible globally.

Phase 2: Add Custom Domain Alias in the Mastodon Instance Configuration

This step requires access to the instance server. If you are not the instance admin, send the following instructions to your admin.

1. Access the Mastodon configuration file
   On the instance server, open the .env.production file located in the Mastodon directory (typically /home/mastodon/live/.env.production).
2. Add the custom domain to the allowed aliases list
   Find the line that starts with WEB_DOMAIN or LOCAL_DOMAIN. Add a new line:
   WEB_DOMAIN=yourcustomdomain.com
   If the line already exists, replace its value with your custom domain. Then add:
   ALLOWED_ALIASES=yourcustomdomain.com
   If multiple aliases are needed, separate them with commas.
3. Restart Mastodon services
   Run the following commands on the server:
   cd /home/mastodon/live
   RAILS_ENV=production bin/tootctl cache clear
   systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming
   This reloads the configuration and clears the cache.

Phase 3: Initiate Account Migration From the New Account

1. Log in to your new Mastodon account
   Open the new instance in your browser and sign in with the account that will receive the followers.
2. Navigate to account preferences
   Click the gear icon or your profile picture, then select Preferences from the dropdown menu.
3. Open the Move settings
   In the left sidebar, click Account, then click Move from a different account.
4. Enter your old account handle
   In the field labeled Old account handle, type your full old account handle including the domain. For example: @oldusername@oldinstance.social.
5. Create and enter a migration code
   On your old account, go to Preferences > Account > Move to a different account. Click Create migration code. Copy the generated code. Return to the new account page and paste the code into the Migration code field.
6. Confirm the migration
   Click the Move followers button. Mastodon will send a confirmation email to the email address on your old account. Open the email and click the confirmation link to finalize the migration.

If the Migration Fails or the Custom Domain Handle Does Not Appear

Custom domain handle shows as unverified

If your profile still shows the old instance domain instead of your custom domain, the DNS CNAME record may not have propagated. Verify the record using a DNS lookup tool. Also, confirm that the instance admin added the custom domain to the ALLOWED_ALIASES line. Without that alias, Mastodon will not associate the custom domain with your account.

Migration code is invalid or expired

Migration codes expire after a short period. If you see an error, generate a new code from the old account and try again. Make sure you copy the entire code exactly, including any hyphens or special characters.

Followers do not move after migration

Follower migration is not instantaneous. It can take up to 24 hours for all followers to appear on the new account. If followers are still missing after 24 hours, check that the old account still exists and has not been deleted. Mastodon requires the old account to remain active for the migration to complete.

Custom Domain Handle vs Standard Mastodon Handle

Item	Custom Domain Handle	Standard Mastodon Handle
Description	Uses your own domain as the handle suffix	Uses the instance domain as the handle suffix
DNS configuration required	Yes, CNAME record pointing to instance server	No
Instance admin action needed	Yes, must add domain to allowed aliases	No
Portability between instances	Requires DNS and alias reconfiguration each time	Simple migration with no extra setup
Branding value	High, shows your own domain	Low, tied to the instance domain

You can now migrate a Mastodon account with a custom domain handle by configuring DNS, updating the instance alias, and running the migration handshake. After migration, verify that your profile displays the custom domain and that followers have moved. For a smoother next migration, keep a record of your DNS settings and the instance configuration changes so you can reuse them on a new instance.