How to Move a Mastodon Instance Between Relays Without Downtime

Moving a Mastodon instance from one relay to another can disrupt federation if not handled correctly. Relays are servers that forward public posts between instances, and changing them improperly may cause missed updates or temporary unreachability. This article explains how to migrate relays smoothly while keeping your instance fully federated and available to users. You will learn the preparation steps, the exact relay swap procedure, and how to verify that federation continues without interruption.

What Are Mastodon Relays and Why Migrate?

A Mastodon relay is a server that collects public posts from multiple instances and redistributes them to all connected instances. Relays help smaller instances discover content from the wider fediverse without following every user individually. When an instance connects to a relay, it sends its own public posts to the relay and receives public posts from all other instances connected to that relay.

You might need to move your instance between relays for several reasons. The current relay may have high latency or frequent outages. A new relay might offer better geographic proximity or stricter moderation policies. Or you might be consolidating multiple relays into one for simpler administration. Whatever the reason, the goal is to change the relay connection without creating a period where your instance is not receiving or sending public posts through any relay.

The key to zero downtime is overlapping relay connections. As long as your instance is connected to at least one active relay at all times, federation continues. The procedure involves adding the new relay, enabling it, waiting for synchronization, and then removing the old relay. This avoids the gap that would occur if you removed the old relay first.

Prerequisites for Relay Migration

Before you begin, confirm you have admin access to your Mastodon instance. You need the ability to add and remove relays from the Administration panel. Also, have the relay server address of the new relay ready. A relay address typically looks like wss://relay.example.com or https://relay.example.com. Contact the relay operator if you do not have the correct address. Finally, ensure your instance is running a recent version of Mastodon, at least version 3.4 or later, to support the relay management features described here.

Steps to Migrate Relays Without Downtime

Follow these exact steps to swap relays while keeping your instance fully federated. Perform each step in the order listed. Do not remove the old relay until you have confirmed the new relay is active and functioning.

1. Open the Relays Administration Page
   Log in to your Mastodon instance as an admin. Click Preferences in the top-right menu. In the left sidebar, navigate to Administration > Relays. This page lists all relays currently connected to your instance.
2. Add the New Relay
   Click the Add new relay button. In the dialog that appears, paste the relay server address of the new relay. Click Add. The relay appears in the list with a status of Pending.
3. Enable the New Relay
   Find the new relay in the list. Click the Enable button next to it. The status changes to Enabled. Your instance now begins sending public posts to the new relay and receiving posts from it. At this point, your instance is connected to both the old and new relays simultaneously.
4. Wait for Synchronization
   Allow at least 10 to 15 minutes for the new relay to synchronize with your instance and for posts to flow through both relays. During this time, check the federated timeline on your instance. You should see posts arriving from instances that use the new relay. If the federated timeline appears empty or stale, wait longer or verify the relay is correctly configured.
5. Verify the New Relay Is Working
   To confirm the new relay is active, visit an external instance that is connected to the same new relay. Search for a public post from your instance on that external instance. If the post appears, the relay is working. Alternatively, ask a user on another instance to check if they can see public posts from your instance.
6. Disable the Old Relay
   Return to the Relays page. Find the old relay in the list and click Disable. The status changes to Disabled. Your instance is now only connected to the new relay.
7. Remove the Old Relay (Optional)
   Once the old relay is disabled, you can remove it entirely by clicking Remove. This cleans up the list and prevents accidental re-enabling. Removal is safe because the relay is already disabled.
8. Final Verification
   After removing the old relay, check the federated timeline again. Posts should continue to arrive normally. Also, test that external instances can still find your instance by searching for your instance domain from a different instance. If everything looks good, the migration is complete.

Common Mistakes and Things to Avoid During Relay Migration

Removing the Old Relay Before Adding the New One

This is the most frequent error. If you remove the old relay first, your instance loses its connection to all relays until you add and enable the new one. During that gap, your instance stops receiving public posts from the relay network. Users may see an empty federated timeline. Always add the new relay first, enable it, and verify it works before touching the old relay.

Using an Incorrect Relay Address

Typing the wrong URL or using an outdated relay address causes the add step to fail or the relay to remain in Pending status indefinitely. Double-check the address with the relay operator. Ensure the URL includes the correct protocol, either wss:// for WebSocket relays or https:// for HTTP relays. Some relays support both, but you must use the one the operator provides.

Not Waiting Long Enough for Synchronization

Synchronization time depends on the relay’s load and network latency. If you disable the old relay too quickly, before the new relay has fully synced, you might lose some posts. The 10- to 15-minute wait is a minimum. On busy relays, wait up to 30 minutes. Check the federated timeline for a steady flow of new posts before proceeding.

Forgetting to Verify Federation from an External Instance

The federated timeline on your own instance only shows posts that have arrived. It does not prove that external instances can see your posts. To fully verify, you must check from another instance. If you cannot find your instance’s posts on an external instance, the new relay may not be distributing your content correctly. In that case, re-enable the old relay and troubleshoot the new relay address or configuration.

Mastodon Relay Types: WebSocket vs HTTP

Item	WebSocket Relay	HTTP Relay
Connection method	Persistent bidirectional connection	HTTP POST and GET requests
Latency	Lower, near real-time delivery	Higher, depends on polling interval
Resource usage on instance	Slightly higher due to persistent socket	Lower, no persistent connection needed
Relay address format	wss://relay.example.com	https://relay.example.com
Common use case	High-traffic instances wanting fast federation	Smaller instances or those with limited resources

When migrating between relays, note the type of each relay. Switching from a WebSocket relay to an HTTP relay may change the latency experience for your users. The migration procedure itself is identical for both types. The key is to have the correct address format for the new relay.

You can now move your Mastodon instance between relays without federation downtime. The core technique is to add and enable the new relay before disabling the old one. Always verify the new relay is working by checking the federated timeline and testing from an external instance. For advanced setups, consider automating the verification step with a script that periodically tests federation using a public API endpoint from a known instance.