Mastodon Relay Failure Recovery: How to Resubscribe Automatically

When a Mastodon relay connection breaks, your instance stops receiving public posts from federated servers that depend on that relay. This usually happens because the relay server went offline, changed its endpoint, or the subscription token expired. Without a working relay, your local timeline becomes quieter and users may miss trending content from outside instances. This article explains why relay subscriptions fail and provides a step-by-step method to resubscribe automatically using a script and system scheduler, so you do not need to manually re-add relays every time they break.

Why Mastodon Relay Subscriptions Fail

A Mastodon relay is a specialized server that redistributes public posts from one instance to many others. Your instance subscribes to a relay by sending a subscription request. The relay then pushes new public posts to your instance. If the relay goes offline for a period, your instance marks the subscription as failed. When the relay comes back, your instance does not automatically re-subscribe.

The most common failure reasons are:

Relay Server Downtime

If the relay server stops responding for more than a few minutes, Mastodon marks the subscription as dead. The relay administrator may restart the server, but your instance will not re-subscribe until you manually re-add the relay or run the subscribe command.

Expired Subscription Tokens

Some relays require a subscription token that expires after 24 to 48 hours. Mastodon does not automatically renew these tokens. When the token expires, the relay rejects your instance and the subscription becomes inactive.

Relay Endpoint URL Changed

If the relay operator moves the relay to a new domain or path, your instance still points to the old URL. The subscribe command fails silently until you update the relay URL in the admin panel.

Steps to Resubscribe to a Mastodon Relay Automatically

Follow these steps to set up automatic resubscription using the Mastodon CLI and a cron job on Linux or Task Scheduler on Windows. This method works for Mastodon instances running on any operating system that supports cron or a scheduled task.

Step 1: Identify the Relay Subscription Status

1. Log in to the Mastodon admin panel
   Go to https://yourinstance.com/admin/settings/relays. You will see a list of all relays your instance has ever subscribed to. Each relay shows a status indicator: green for active, red for failed, and gray for pending.
2. Note the relay URLs
   For each relay with a red status, copy the full relay URL. You will need these URLs later for the automated script.

Step 2: Create the Resubscription Script

1. Open a terminal on your Mastodon server
   Use SSH or the server console to access the machine running your Mastodon instance.
2. Create a new shell script file
   Run nano /home/mastodon/resubscribe_relays.sh. Replace mastodon with the username under which Mastodon runs on your system.
3. Write the script content
   Paste the following lines into the file. Replace /home/mastodon/live with the actual path to your Mastodon installation directory.

   #!/bin/bash
   cd /home/mastodon/live
   RAILS_ENV=production bin/tootctl relays subscribe --all
   

4. Save and exit
   Press Ctrl+X, then Y, then Enter to save the file.
5. Make the script executable
   Run chmod +x /home/mastodon/resubscribe_relays.sh.

Step 3: Test the Script Manually

1. Run the script
   Execute sudo -u mastodon bash /home/mastodon/resubscribe_relays.sh. Replace mastodon with the actual Mastodon system user.
2. Check the output
   The script will output a message for each relay: either “Subscribed to relay” or “Already subscribed.” If you see errors, verify the relay URLs in the admin panel and ensure the Mastodon user has write permissions to the live directory.
3. Verify in the admin panel
   Refresh the relays page in your browser. The status for previously failed relays should now be green or gray. If it remains red, the relay may still be offline.

Step 4: Schedule Automatic Execution

1. Open the crontab for the Mastodon user
   Run sudo -u mastodon crontab -e. If this is the first time, select a text editor when prompted.
2. Add a cron job line
   Insert the following line at the bottom of the file:
   0 6 /home/mastodon/resubscribe_relays.sh
   This runs the script every day at 6:00 AM. Adjust the time to match your preferred schedule. Use a cron time calculator if needed.
3. Save and exit
   Press Ctrl+X, then Y, then Enter. Cron will confirm the new job is installed.

Step 5: Verify the Scheduled Task

1. List active cron jobs
   Run sudo -u mastodon crontab -l. You should see the line you added.
2. Wait for the scheduled run
   Allow the cron job to run at the configured time. After it runs, check the relay status in the admin panel. The script should have re-subscribed to any relays that were marked as failed.

If the Automated Resubscription Still Fails

Relay URL Is Incorrect

If the script runs but the relay status remains red, the relay URL stored in your admin panel may be outdated. Go to Admin > Relays and click the edit button next to the failed relay. Verify the URL matches the current relay endpoint. If the relay operator changed the URL, you must remove the old relay and add the new one manually. After updating, run the script again.

Relay Is Permanently Offline

Some relays shut down permanently. The script cannot re-subscribe to a relay that no longer exists. Check the relay’s status page or contact the relay operator. If the relay is gone, remove it from your admin panel and find an alternative relay from the Mastodon relay registry at https://relaylist.com.

Permission Denied When Running the Script

If you see “Permission denied” errors, the Mastodon user does not have execute permission on the script or the script path is incorrect. Run ls -l /home/mastodon/resubscribe_relays.sh to confirm the script exists and has executable permissions. Ensure the cron job line uses the full absolute path to the script.

Manual Resubscription vs Automated Script

Item	Manual Resubscription	Automated Script with Cron
Setup time	30 seconds per relay	10 minutes once
Reliability	Depends on human memory	Runs daily regardless
Error handling	None	Logs output to syslog
Recovery speed	Hours to days	Within 24 hours
Requires server access	No	Yes

Automated resubscription is the best choice for instance administrators who manage multiple relays and cannot monitor them constantly. Manual resubscription works for small instances with one or two relays that rarely fail.

After setting up the cron job, your Mastodon instance will automatically re-subscribe to any failed relay within 24 hours. Check the relay status once a week to confirm the script runs without errors. If you manage multiple instances, consider centralizing relay management with a shared script that runs on each server.