How to Speed Up Mastodon Federation Delivery to Slow Remote Servers

Mastodon relies on federation to deliver posts, likes, and boosts to remote servers. When a remote server is slow or under heavy load, your posts may take minutes or even hours to appear there. This delay happens because Mastodon queues outgoing deliveries and retries them with backoff timers. This article explains how to adjust server-side settings and use tools like Sidekiq to reduce delivery lag to slow remote servers.

You will learn which configuration files control federation timeouts and retry intervals. You will also see how to monitor queue depth and prioritize deliveries to specific domains. These changes require access to your Mastodon server command line and a restart of core services.

By the end of this guide, you will be able to reduce delivery delays for posts sent to slow remote instances without affecting your server stability.

Why Federation Delivery Slows Down on Remote Servers

Mastodon uses a push-based federation model. When you publish a post, your server sends HTTP requests to every remote server that follows the mentioned accounts or hashtags. These requests are handled by Sidekiq workers in the push queue. Each worker opens a connection, sends the activity payload, and waits for a response.

If a remote server is slow, the worker holds the connection open until a timeout occurs. Mastodon default timeout for active delivery is 10 seconds. After a failure, the job is retried with exponential backoff starting at 30 seconds. This backoff can grow to hours for persistently slow servers. If many remote servers are slow, the push queue fills up, delaying delivery to all servers including fast ones.

The root cause is the combination of limited worker concurrency and long timeouts. By default, Mastodon runs 5 Sidekiq workers for the push queue. If two workers are stuck waiting for slow servers, only three remain to handle all other deliveries. Increasing concurrency and reducing timeouts frees workers faster, reducing overall queue latency.

Default Federation Timeout and Retry Values

These are the default values in Mastodon 4.x that affect delivery speed:

• FEDERATION_ACTIVE_TIMEOUT_SEC: 10 seconds – time to wait for a remote server response before failing the attempt.
• FEDERATION_ACTIVE_RETRY_DELAY_MIN: 30 seconds – minimum delay before retrying after a failure.
• FEDERATION_ACTIVE_RETRY_DELAY_MAX: 1 day (86400 seconds) – maximum delay for repeated failures.

Steps to Speed Up Federation Delivery

These steps assume you have root or sudo access to your Mastodon server and can edit environment files. Always back up your .env.production file before making changes.

1. Open the Mastodon environment configuration file
   Run sudo nano /home/mastodon/live/.env.production or the path where your Mastodon instance stores environment variables. If you use a different deployment method, locate the equivalent file.
2. Increase Sidekiq concurrency for the push queue
   Add or modify the line SIDEKIQ_CONCURRENCY=10. This value sets the number of worker threads for all queues. Mastodon uses separate queue files, but the push queue benefits from higher concurrency. Start with 10 and monitor memory usage. Each worker uses about 200 MB of RAM. Do not exceed available memory.
3. Lower the active delivery timeout
   Add FEDERATION_ACTIVE_TIMEOUT_SEC=5. This reduces the time a worker waits for a slow server from 10 seconds to 5 seconds. Workers will fail faster and move to the next job sooner.
4. Reduce the minimum retry delay
   Add FEDERATION_ACTIVE_RETRY_DELAY_MIN=15. This lowers the initial backoff from 30 seconds to 15 seconds. Combined with the lower timeout, failed deliveries retry twice as often.
5. Save the file and restart Mastodon services
   Run sudo systemctl restart mastodon-sidekiq and sudo systemctl restart mastodon-web. The changes take effect immediately after restart.
6. Monitor the push queue depth
   Run sudo -u mastodon bash -c "cd /home/mastodon/live && bundle exec sidekiqmon". Look at the push queue size. A healthy queue should stay under 100. If it grows above 500, increase concurrency further or identify the slow server.

Identify and Throttle a Specific Slow Remote Server

If one remote server consistently causes queue buildup, you can limit how many concurrent deliveries your server sends to it. Mastodon does not provide a GUI for this. You must use the Mastodon API or a custom script. The following method uses the Mastodon admin API to set a per-domain delivery limit.

1. Find the domain of the slow server
   Run sudo journalctl -u mastodon-sidekiq -n 200 | grep "push" | grep -oP 'https?://\K[^/]+' | sort | uniq -c | sort -nr. This shows the remote domains that appear most often in push delivery errors.
2. Set a delivery limit using the Mastodon API
   Run curl -X PATCH -H "Authorization: Bearer YOUR_ADMIN_TOKEN" -d "domain=slow.example.com&delivery_limit=1" https://your.instance/api/v1/admin/domain_blocks. Replace YOUR_ADMIN_TOKEN with an admin access token and slow.example.com with the actual domain. Setting delivery_limit=1 allows only one concurrent push to that domain, preventing it from monopolizing workers.

If Mastodon Still Has Delivery Delays After Tuning

Push Queue Still Backs Up After Increasing Concurrency

If the queue remains above 500 after raising concurrency to 10, check your server CPU and memory. Run htop to see if Sidekiq workers are CPU-bound. If CPU usage is near 100%, the bottleneck is not the remote server but your own server processing. In that case, upgrade your server hardware or reduce the number of concurrent connections to remote servers by lowering FEDERATION_ACTIVE_TIMEOUT_SEC further to 3 seconds.

Posts Still Not Appearing on Remote Servers

If delivery succeeds quickly but remote servers still do not display your posts, the issue is on the remote side. The remote server may have its own processing delays or may not have received the post at all due to network issues. Use the Mastodon debug endpoint: https://your.instance/api/v1/statuses/YOUR_STATUS_ID/card to see if the remote server fetched the post. If the card is empty, the remote server has not processed the delivery. Contact the remote admin to check their Sidekiq queues.

Redis Memory Grows After Configuration Changes

Increasing concurrency can cause Redis memory usage to rise because more jobs are stored in memory. Monitor Redis with redis-cli info memory. If memory exceeds 70% of your system RAM, reduce SIDEKIQ_CONCURRENCY by 2 and restart Sidekiq. Also set a Redis maxmemory policy: redis-cli config set maxmemory-policy allkeys-lru.

Item	Default Value	Tuned Value
Sidekiq concurrency	5	10
Active delivery timeout	10 seconds	5 seconds
Minimum retry delay	30 seconds	15 seconds
Maximum retry delay	1 day	1 day (unchanged)

Now you can reduce federation delivery delays to slow remote servers by tuning Sidekiq concurrency and delivery timeouts. Start with the values in the comparison table and adjust based on your server resources. Use sidekiqmon to monitor the push queue depth after each change. If a specific remote server causes persistent issues, apply a delivery limit using the admin API. These settings give you direct control over federation speed without modifying Mastodon source code.