Mastodon Relay Subscription Persistence: How to Verify After Upgrade

After upgrading your Mastodon server, relay subscriptions may stop working without any visible error. The relay connection can silently break, causing your instance to miss federated content from subscribed relays. This typically happens because the upgrade process resets internal database connections or changes the relay handshake protocol. This article explains how to verify that your relay subscriptions survived the upgrade and how to re-establish them if they did not.

Why Mastodon Relay Subscriptions Break During an Upgrade

Mastodon relays work by exchanging subscription requests between your instance and a relay server. The relay server then pushes public posts from all subscribed instances to yours. When you upgrade Mastodon, several things can disrupt this connection.

The database migration that runs during the upgrade may reset the enabled flag on relay records. This happens because some upgrade scripts drop and recreate tables or change column types. If the migration does not preserve the existing subscription state, the relay appears as enabled in the database but the actual subscription handshake is lost.

Another common cause is that the upgrade changes the way Mastodon communicates with external services. For example, a change in the HTTP signature algorithm or the ActivityPub protocol version can cause the relay to reject your instance’s subscription request. The relay server sees an invalid signature and silently drops the connection.

Finally, the Sidekiq process that handles relay subscription renewal may restart during the upgrade. If the renewal job fails to run after the restart, the subscription expires. The relay then stops sending new content to your instance.

Steps to Verify Relay Subscription Status After an Upgrade

Follow these steps in order to check whether your relay subscriptions are still active. Start with the web interface and proceed to the command line if needed.

1. Open the Relays administration page
   Log in to your Mastodon instance as an admin. Go to Preferences > Administration > Relays. This page lists all relay servers your instance is subscribed to. Check the status column. If a relay shows “Enabled” but the last contact date is older than 24 hours, the subscription may be broken.
2. Check Sidekiq for relay-related job failures
   Open your Sidekiq dashboard at https://your-instance/sidekiq. Look at the Queues tab for the scheduler and pull queues. If you see a high number of retries or dead jobs related to RelayWorker or ActivityPub::FetchRelayActorService, the upgrade likely broke the subscription.
3. Test the relay connection manually
   In the Rails console, run Relay.find_each { |r| puts "#{r.id}: #{r.state}" }. This prints the internal state of each relay. A state of "enabled" means the subscription should be active. A state of "disabled" or nil means the subscription is broken.
4. Re-enable all relay subscriptions
   If any relay shows a broken state, run Relay.find_each(&:subscribe!) in the Rails console. This sends a fresh subscription request to each relay. Wait 5 minutes, then check the Relays page again. The last contact timestamp should update to the current time.
5. Verify incoming relay content
   Open the federated timeline on your instance. Look for posts from accounts that belong to other instances known to use the same relay. If you see new posts from those instances within 10 minutes, the relay subscription is working correctly.

If Mastodon Still Has Issues After the Main Fix

Relay shows as enabled but no content arrives

This usually means the relay server has blocked your instance due to a signature mismatch. Check your Mastodon logs with tail -f log/production.log | grep relay. If you see “HTTP signature verification failed” messages, the upgrade changed your instance’s private key or the signature algorithm. Contact the relay operator and ask them to re-add your instance. Then run Relay.find_each(&:subscribe!) again.

Sidekiq queue grows with relay retry jobs

If Sidekiq shows hundreds of retries for relay jobs, the relay server may be temporarily offline or rate-limiting your instance. Wait 30 minutes and check again. If the retries continue, remove the relay subscription from the Relays page and add it again manually. This forces a fresh handshake.

Relay subscription disappears from the admin page

This is rare but can happen if the upgrade migration deleted the relay records. Check the database directly with psql -d mastodon_production -c "SELECT FROM relays;". If the table is empty, you must add each relay subscription again using the web interface. Use the Add relay button on the Relays page and paste the relay URL.

Mastodon Relay Subscription Persistence: Manual vs Automated Renewal

Item	Manual resubscription	Automated Rails console command
Method	Remove and re-add each relay URL via the web interface	Run Relay.find_each(&:subscribe!) after upgrade
Time required	2-5 minutes per relay	30 seconds for all relays
Risk of data loss	None, but you must know each relay URL	None, but requires Rails console access
Best used when	Relay list is empty after upgrade	Relays still appear in the database but are broken

After verifying your relay subscriptions, you can confirm that your instance is receiving federated content again by checking the federated timeline for new posts from relayed instances. If you manage multiple relays, consider writing a cron job that runs Relay.find_each(&:subscribe!) weekly to prevent future subscription drift. This command is safe to run even on working subscriptions because Mastodon ignores duplicate subscription requests.