Mastodon Relay Idle Timeout: How to Detect Stale Connections

Mastodon relays can stop forwarding new posts after a period of inactivity. When a relay connection becomes idle, the remote server may close the TCP socket without notice. Your Mastodon instance continues to show the relay as connected in the admin panel, but no new content flows through. This article explains how to detect stale relay connections and restore them.

An idle timeout occurs when the relay server closes an inactive HTTP or WebSocket connection after a set period. Mastodon relays use long-lived connections to push public posts from one instance to another. If no data is exchanged for several minutes, the remote server tears down the connection. The local instance does not always detect this drop, leaving the relay in a zombie state.

This guide covers the root cause of idle timeouts, the exact commands to check connection status, and the steps to force a reconnect. You will also learn how to monitor relay health automatically.

Why Mastodon Relay Connections Go Stale

Mastodon relays use a push model. When your instance publishes a public post, the PushRelayWorker sends it to every configured relay endpoint. The relay then distributes the post to all connected instances. This push happens over HTTP with a keep-alive header that tells both sides to hold the connection open for further requests.

The problem is that many relay servers, especially those behind load balancers or CDNs, enforce idle timeouts of 30 to 60 seconds. If your instance does not produce a public post within that window, the remote server closes the connection. The local Mastodon process that handles the push may not receive the TCP RST or FIN packet, so it continues to believe the connection is active.

When the next public post arrives, the worker attempts to push it over the closed socket. This fails silently in many cases because the worker does not retry the push. The relay effectively stops working until an administrator manually resubscribes.

Steps to Detect and Reconnect Stale Mastodon Relays

1. Open the Mastodon admin panel
   Log into your Mastodon instance with an admin account. Navigate to Preferences > Administration > Relays. This page lists all configured relays and shows the last time your instance successfully pushed a post to each relay.
2. Check the last push timestamp
   Look at the Last pushed column for each relay. If the timestamp is older than 10 minutes and your instance has been publishing public posts during that period, the connection is stale. A healthy relay should show a timestamp within the last few minutes.
3. Verify relay status in the Sidekiq dashboard
   Go to /sidekiq on your instance. Click Queues and look for the push queue. If the queue has a backlog of jobs or shows PushRelayWorker jobs with high latency, the relay connection may be failing. A queue depth above 10 is a strong indicator of a problem.
4. Check system logs for connection errors
   SSH into your Mastodon server. Run journalctl -u mastodon-sidekiq -n 50 --no-pager and search for lines containing PushRelayWorker or relay. Look for messages like Connection refused or Timeout. These confirm a stale or broken relay connection.
5. Force a reconnect from the Rails console
   Run cd /home/mastodon/live && RAILS_ENV=production bundle exec rails c. At the Rails prompt, type Relay.find_each(&:subscribe) and press Enter. This command triggers a fresh subscribe request for every relay. Exit the console with exit. Check the admin panel again after 30 seconds. The Last pushed timestamp should update.
6. Restart Sidekiq if the reconnect fails
   If the Rails console command does not restore the relay, restart the Sidekiq service: sudo systemctl restart mastodon-sidekiq. This clears any stuck worker processes and forces a fresh connection attempt on the next public post.

If Relays Still Disconnect After Reconnecting

Relay server enforces a very short timeout

Some relay operators configure idle timeouts as low as 15 seconds. If your instance publishes fewer than one public post per 15 seconds, the connection will drop. The only fix is to contact the relay operator and request a longer timeout, or to switch to a relay with a more lenient configuration.

Your instance is behind a reverse proxy that terminates keep-alive

Nginx or Apache can be configured to drop idle connections early. Check your proxy configuration for directives like proxy_read_timeout or keepalive_timeout. Increase proxy_read_timeout to 300 seconds and keepalive_timeout to 120 seconds. Then reload the proxy: sudo systemctl reload nginx.

Relay endpoint has changed or is no longer active

Relay operators sometimes move their service to a new URL without updating the old endpoint. Remove the relay from Administration > Relays by clicking the Delete button. Then add the relay again using the correct URL provided by the operator.

Mastodon Relay vs Direct Federation: Connection Behavior

Item	Relay	Direct Federation
Connection type	Persistent HTTP push to relay server	Short-lived HTTPS POST per delivery target
Idle timeout impact	Connection drops silently; no retry	Each delivery is independent; no persistent connection to lose
Detection method	Check Last pushed timestamp in admin panel	Check Sidekiq failed jobs or delivery logs
Recovery	Manual reconnect via Rails console or restart	Automatic retry by Sidekiq with exponential backoff
Best for	Small instances that want to see all public posts from a topic	Instances that need reliable delivery to specific remote users

You can now identify stale Mastodon relay connections by checking the Last pushed timestamp in the admin panel and by inspecting the Sidekiq push queue. Use the Rails console command Relay.find_each(&:subscribe) to force a reconnect without restarting services. For long-term prevention, consider adding a cron job that runs the reconnect command every five minutes to automatically recover from idle timeouts before they cause visible delays.