When you subscribe to a Mastodon relay, your instance begins pulling in public posts from every server connected to that relay. Over time, a relay can flood your federated timeline with irrelevant or low-quality content, slowing down your server and overwhelming your moderators. Removing the relay cleanly requires more than just toggling a switch — you must also purge the cached data it has already delivered. This article explains how to unsubscribe from a Mastodon relay and clear the associated data so your instance returns to normal performance.
Key Takeaways: Mastodon Relay Removal
- Administration > Relays page: Lists all active relays and provides the Remove button to unsubscribe.
- mastodon:feeds:clear or Sidekiq scheduler: Deletes all cached statuses from the relay after removal.
- Administration > Federation > Domains: Lets you suspend or limit the relay domain to prevent re-subscription.
What a Mastodon Relay Does and Why You Might Remove One
A Mastodon relay is a server that acts as a hub for public post distribution. When your instance subscribes to a relay, it sends its public posts to the relay, and the relay forwards public posts from all other subscribed instances back to yours. This boosts the volume of content in your federated timeline without requiring your users to follow individual accounts on those remote servers.
Relays are useful for small instances that want to discover new content quickly. However, they come with downsides:
They can introduce spam, hate speech, or content that violates your instance rules. They also increase database and storage usage because every post from every relay-connected instance is stored on your server, even if no local user interacts with it. If your instance is growing or your moderation team is small, an overly active relay can become a burden.
Common reasons for relay removal include:
- The relay is sending too much low-quality content.
- The relay has been compromised or is spreading illegal material.
- Your instance has grown enough to no longer need relay-based discovery.
- You want to switch to a different relay with better content filtering.
Whatever the reason, the removal process has two parts: unsubscribing from the relay and cleaning up the data it already delivered.
Steps to Unsubscribe From a Mastodon Relay
These steps assume you have administrator access to your Mastodon instance. You will use the web interface and the command-line administration tool.
- Log in as an admin
Open your Mastodon instance in a web browser and sign in with an account that has the Admin role. Only admins can modify relay subscriptions. - Navigate to Administration > Relays
Click the gear icon in the top right corner, then select Administration. In the left sidebar, click Relays. This page shows all relays your instance is currently subscribed to, along with their status and the date they were added. - Click the Remove button next to the relay
Each relay entry has a Remove button. Click it. A confirmation dialog appears. Click OK or Confirm. Mastodon immediately sends an unsubscribe request to the relay server. The relay is removed from your list, and your instance stops sending or receiving posts through it. - Purge cached data from the relay
Removing the relay does not delete the posts already stored in your database. To clean up those posts, open a terminal on your Mastodon server and run the following command as the mastodon user:RAILS_ENV=production bin/tootctl relays remove [RELAY_URL]
Replace [RELAY_URL] with the full URL of the relay you removed, for example https://relay.example.com. This command deletes all statuses that were delivered through that relay and are not linked to any local interaction such as a favorite or boost. If the relay was very active, this operation may take several minutes. - Suspend the relay domain to prevent re-subscription
Go to Administration > Federation > Domains. Search for the relay domain. Click the domain, then click Suspend. This blocks the relay server from connecting to your instance again. If you only want to limit visibility without a full block, choose Limit instead.
After completing these steps, your instance will no longer receive new posts from the relay, and the old posts from that relay will be removed from your database.
If Mastodon Relay Removal Does Not Work as Expected
The Remove button is grayed out or missing
This can happen if your admin account does not have full permissions. Go to Administration > Users, find your account, and make sure the Admin role is enabled. Also check if the relay is in a pending state — sometimes a relay subscription fails to establish. In that case, you can delete the relay entry directly from the database using the mastodon:relays:purge Rake task.
Cached posts remain after running tootctl relays remove
The tootctl command only removes statuses that are not linked to any local interaction. If a local user has favorited or boosted a post from the relay, that post is retained. To remove all relay posts regardless of interactions, you must use a more aggressive approach: suspend the relay domain first, then run the Sidekiq scheduler to clean up orphaned records. In rare cases, you may need to manually delete entries from the statuses table using the Rails console, but this is not recommended for production instances without database expertise.
New posts from the relay keep appearing after removal
This usually means the relay domain was not suspended or limited. Even after you unsubscribe, the relay may still try to push posts to your instance if your server is still accepting connections from it. Go to Administration > Federation > Domains, find the relay domain, and set it to Suspend. If you still see posts, check if another relay you are subscribed to is forwarding content from the same source.
Mastodon Relay Removal: Web UI vs Command Line
| Item | Web UI | Command Line |
|---|---|---|
| Unsubscribe from relay | Administration > Relays > Remove | bin/tootctl relays remove [URL] |
| Purge cached posts | Not available | bin/tootctl relays remove [URL] (deletes non-interacted posts) |
| Block relay domain | Administration > Federation > Domains > Suspend | bin/tootctl domains suspend [DOMAIN] |
| View all relay subscriptions | Administration > Relays | bin/tootctl relays list |
The web UI is sufficient for simple unsubscription. Use the command line when you need to purge data or automate the removal across multiple relays.
After removing a relay, you can subscribe to a different relay that offers better content filtering. Look for relays with a code of conduct or a whitelist of instances. You can also run your own relay if you want full control over what is distributed.
If you manage a large instance, consider using the Mastodon API to programmatically monitor relay health and remove relays that exceed a certain volume threshold. The tootctl relays command accepts a –concurrency flag to speed up removal of multiple relays in sequence.