How to Migrate a Mastodon Account With Custom Domain Setup

Moving a Mastodon account to a new instance is straightforward for most users, but adding a custom domain introduces extra steps. Your custom domain is tied to your old instance’s server records, and the migration process must update these records to point to your new home. If you skip these steps, your followers may see your old profile or encounter errors when visiting your custom domain. This article explains the complete process to migrate your Mastodon account while keeping your custom domain active and redirecting traffic correctly.

Why a Custom Domain Complicates Mastodon Account Migration

Mastodon uses WebFinger, an open protocol, to discover accounts across federated instances. When someone searches for your handle @you@social.example.com, the Mastodon server queries social.example.com/.well-known/host-meta to find your actual instance. If you move your account but do not update the DNS records and WebFinger endpoint, the old domain still points to the old instance. This causes federation errors, broken profile links, and lost follower updates.

The migration process has two independent parts. The first part is the account-level move: you tell Mastodon to transfer followers, lists, and settings from your old account to a new account on a different instance. The second part is the domain-level update: you change DNS and web server configuration so that your custom domain resolves to the new instance. Both parts must succeed for a seamless transition.

Steps to Migrate Your Mastodon Account While Keeping a Custom Domain

Complete these steps in order. Do not start the account migration until you have access to both the old and new Mastodon accounts and can edit DNS settings for your custom domain.

Step 1: Prepare the New Mastodon Account

1. Create an account on your target instance.
   Sign up on the new Mastodon instance where you want to move. This instance can be a different server or a self-hosted instance with a different domain.
2. Enable account migration on the new account.
   Go to Preferences > Account > Move from a different account. Copy the migration code displayed on this page. This code is a one-time token that proves you control the new account.

Step 2: Initiate the Account Move From the Old Account

1. Log into your old Mastodon account.
   Use the account that currently has your custom domain attached.
2. Navigate to Preferences > Account > Move to a different account.
   Paste the migration code you copied from the new account into the text field. Enter your old account password to confirm the move.
3. Submit the migration request.
   Mastodon will send a confirmation email to the address associated with your old account. Click the confirmation link within 24 hours. Once confirmed, the old account will display a redirect notice on its profile page, and follower requests will be sent to the new account.

Step 3: Update DNS Records for Your Custom Domain

1. Log into your domain registrar or DNS hosting provider.
   This is the service where you manage DNS records for your custom domain, such as Cloudflare, Namecheap, or your hosting panel.
2. Locate the existing CNAME or A record for your custom domain subdomain.
   If your custom domain is social.example.com, find the CNAME record that currently points to your old Mastodon instance. If you use an A record, note the current IP address.
3. Change the CNAME record to point to the new instance’s hostname.
   Replace the old target with the new instance’s domain, such as new-instance.social. If your new instance uses a different IP address for an A record, update the IP address. Save the record. DNS propagation can take up to 48 hours, but it often completes within minutes.

Step 4: Configure the New Instance to Serve the Custom Domain

1. Add the custom domain to the new instance’s web server configuration.
   If you run a self-hosted instance, edit the Nginx or Apache configuration to include a server block for social.example.com. Point the document root to the Mastodon public directory. If you use a hosted instance, contact the instance administrator to add your custom domain as an alias.
2. Set up SSL/TLS for the custom domain.
   Obtain a Let’s Encrypt certificate for social.example.com on the new server. Use Certbot or your hosting panel’s SSL tool. Without HTTPS, Mastodon clients and other instances will reject the connection.
3. Verify the WebFinger endpoint responds correctly.
   Open a browser and navigate to https://social.example.com/.well-known/host-meta. You should see an XML response containing the link to the Mastodon API. If you see a 404 or a redirect to the old instance, the web server configuration is incomplete.

Step 5: Test the Migration

1. Search for your account from a different Mastodon instance.
   Log into any Mastodon instance other than your old or new one. In the search bar, type @you@social.example.com. The search should return your new account profile, not the old one.
2. Send a test follow request.
   From the same external instance, try to follow your account. The request should arrive in your new account’s follow requests. If it goes to the old account, DNS or WebFinger is still pointing to the old instance.
3. Check the old account profile.
   Visit the old account’s profile on its original instance. It should show a banner stating that the account has moved to your new domain. The redirect message confirms the account-level migration succeeded.

Common Issues With Mastodon Custom Domain Migration

Followers Do Not Transfer After the Move

If your followers remain on the old account, the migration code may have been entered incorrectly, or the confirmation email was not clicked. Recheck the steps in section 2. Ensure you used the correct migration code from the new account and confirmed the email within 24 hours. If the code expired, generate a new one and repeat the move.

Custom Domain Shows Old Profile After DNS Update

DNS propagation delays can cause this. Wait up to 48 hours and flush your local DNS cache using ipconfig /flushdns on Windows or sudo dscacheutil -flushcache on macOS. If the problem persists, your web server may still be serving the old instance’s content. Verify that the reverse proxy on the new instance correctly forwards requests for the custom domain to the Mastodon process.

WebFinger Returns 404 or Wrong Instance

This indicates the new instance’s web server is not configured to handle the .well-known path for the custom domain. Check that the server block for social.example.com includes a location block for /.well-known/ that proxies to the Mastodon backend. The default Mastodon Nginx configuration includes this block. If you use a hosted instance, ask the administrator to add your custom domain as an alias in the Mastodon configuration file.

Mastodon Custom Domain Migration vs Standard Migration

Item	Standard Migration	Custom Domain Migration
DNS changes required	No	Yes — update CNAME or A record to new instance
WebFinger configuration	Handled by instance domain	Must be configured on new instance’s reverse proxy
SSL/TLS certificate	Provided by instance	Must be obtained for custom domain on new server
Account move steps	Same: use migration code and confirm email	Same: use migration code and confirm email
Follower transfer	Automatic after move	Automatic after move, but DNS must resolve to new instance for new follows

Migrating a Mastodon account with a custom domain requires attention to both the account-level move and the domain-level DNS and web server configuration. The account move transfers your followers, while the DNS update ensures that future federation requests reach your new instance. Test the setup thoroughly after completing both parts.