Mastodon Federation Dead Server Detection: How to Configure

Mastodon servers communicate with each other through federation, sharing posts and profile updates across instances. When a remote server goes offline permanently or becomes unreachable, it can cause delays, failed deliveries, and wasted system resources on your instance. Mastodon includes a built-in mechanism called dead server detection that identifies and stops trying to reach these unreachable servers. This article explains how dead server detection works, how to configure its settings in your Mastodon administration panel, and what to do when detection does not activate as expected.

How Mastodon Dead Server Detection Works

Mastodon tracks every outbound federation request to a remote server. Each request includes a timestamp of the last successful delivery or receipt. When a remote server stops responding, Mastodon continues retrying for a period defined by the instance administrator. After that period expires without any successful contact, Mastodon marks the server as dead.

Once a server is marked dead, Mastodon stops sending new activities to it. This reduces network traffic, lowers CPU usage, and prevents delivery errors from filling up logs. Dead servers are re-checked periodically. If the server comes back online and responds to a new request, Mastodon removes the dead flag and resumes normal federation.

The detection system uses two main parameters: the dead server threshold and the dead server retry interval. The threshold defines how long Mastodon waits before marking a server as dead. The retry interval defines how often Mastodon checks a dead server to see if it has recovered.

Configuring Dead Server Detection in the Mastodon Administration Panel

Before you begin, you must be logged in as an administrator on your Mastodon instance. The settings are available only to users with the Admin or Owner role.

1. Open the Administration Panel
   Click the gear icon in the top-right corner of the Mastodon interface. From the dropdown menu, select Administration.
2. Navigate to Server Rules
   In the left sidebar, click Server Rules. This section controls federation behavior and content moderation policies.
3. Locate the Federation Section
   Scroll down until you see the heading Federation. Below it, you will find two fields: Dead server threshold and Dead server retry interval.
4. Set the Dead Server Threshold
   Enter the number of hours without successful contact before a remote server is considered dead. The default value is 48 hours. For a more aggressive detection, reduce the value to 24 hours. For a more lenient policy, increase it to 72 hours.
5. Set the Dead Server Retry Interval
   Enter the number of hours between retry attempts to a dead server. The default is 12 hours. Lower values check more often but increase network traffic. Higher values reduce traffic but delay recovery detection.
6. Save Changes
   Click the Save changes button at the bottom of the page. Mastodon applies the new settings immediately. No restart is required.

Configuring Dead Server Detection via Environment Variables

For Mastodon instances running on Docker or as standalone services, you can set dead server detection parameters through environment variables. These values override the administration panel settings if both are configured.

1. Locate Your Configuration File
   For Docker installations, open the docker-compose.yml file. For standalone installations, open the .env.production file in the Mastodon root directory.
2. Add or Edit the Environment Variables
   Add the following lines to the file:
   DEAD_SERVER_THRESHOLD=48
DEAD_SERVER_RETRY_INTERVAL=12
   Replace the numbers with your desired values in hours.
3. Restart Mastodon Services
   For Docker, run docker-compose down && docker-compose up -d. For standalone, run systemctl restart mastodon- or the equivalent command for your init system.

If Dead Server Detection Does Not Activate

Dead Server Detection Not Marking Servers as Dead

If you notice that unreachable servers are not being marked as dead, the most common cause is a threshold value that is too high. Check your current threshold setting in the administration panel. If it is set to 168 hours (one week) or more, Mastodon will wait a very long time before flagging a server. Reduce the threshold to 48 hours or less.

Another possible cause is that the remote server sends periodic heartbeat requests even though it does not process normal federation traffic. Mastodon counts any successful contact as a sign of life. In this case, you cannot override the detection logic without modifying the Mastodon source code.

Dead Server Detection Marking Active Servers as Dead

If active servers are incorrectly flagged as dead, the threshold may be too low. A value of 12 hours or less can cause false positives if a server experiences temporary downtime. Increase the threshold to 48 hours or higher. Also check your network connectivity to ensure your instance can reach the remote server. A firewall or DNS issue on your side can make any server appear dead.

Retry Interval Not Working After Configuration

If you changed the retry interval but Mastodon does not seem to re-check dead servers at the new rate, verify that the environment variables are not overriding the panel settings. Environment variables take precedence. Remove the DEAD_SERVER_RETRY_INTERVAL line from your configuration file if you want the panel setting to apply. Then restart Mastodon services.

Mastodon Dead Server Detection: Administration Panel vs Environment Variables

Item	Administration Panel	Environment Variables
Configuration method	Web interface under Server Rules > Federation	Edit docker-compose.yml or .env.production file
Requires restart	No	Yes
Override priority	Lower priority	Higher priority
Accessible to non-admin users	No	No

You can now configure dead server detection on your Mastodon instance to match your federation policy. Start by setting the dead server threshold in the administration panel to 48 hours and the retry interval to 12 hours. If your instance runs behind a reverse proxy, ensure the proxy does not cache or block federation traffic, as that can interfere with detection accuracy. For advanced setups, consider monitoring your federation logs with the tootctl media refresh command to identify servers that may need manual intervention.