Mastodon Federation Background Refresh Behavior: How to Schedule

Mastodon instances periodically refresh their connection to other servers to keep the federated timeline up to date. This background refresh process pulls new posts, boosts, and replies from remote instances that your users follow or interact with. Without a properly configured refresh schedule, your instance may show stale content or miss updates from the broader Fediverse. This article explains how Mastodon handles background federation refreshes and how you can adjust the schedule to match your server’s performance and content freshness needs.

How Mastodon Handles Federation Background Refresh

Mastodon does not continuously poll every remote instance in real time. Instead, it uses a background job system called Sidekiq to periodically fetch updates from remote servers that your instance has interacted with. The key scheduler is Scheduler::FollowRecommendationsScheduler, which runs at a configurable interval and queues jobs to fetch statuses from the remote accounts that your local users follow.

The refresh process works like this:

• When a local user follows an account on another instance, Mastodon subscribes to that remote account’s public feed via the ActivityPub protocol.
• The background scheduler periodically checks each subscribed remote account for new posts.
• New posts are pulled into your instance’s database and appear in the federated timeline and home feeds of local followers.

The default refresh interval depends on your Sidekiq configuration. By default, Mastodon runs the follow recommendations scheduler every 2 hours. This means that content from remote instances may be up to 2 hours old by the time it appears on your instance. For high-traffic instances or communities that need near-real-time updates, this default may be too slow.

The refresh schedule is controlled by two main components:

Sidekiq Scheduler Configuration

Mastodon uses the sidekiq-scheduler gem to define periodic jobs. Each scheduler job has a cron expression that determines how often it runs. The relevant scheduler for federation refresh is defined in config/sidekiq.yml under the scheduler: section.

Environment Variable FETCH_REMOTE_STATUSES

This environment variable acts as a master switch. Set it to true to enable background fetching of remote statuses. Set it to false to disable the feature entirely. Disabling it means your instance will only receive remote content that is pushed to it in real time via ActivityPub, which may reduce server load but also reduce content freshness.

Steps to Schedule or Adjust Federation Background Refresh

Follow these steps to change the refresh schedule on your Mastodon instance. You need shell access to your server and the ability to edit configuration files. All changes require a restart of the Sidekiq service.

1. Locate the Sidekiq configuration file
   Open /home/mastodon/live/config/sidekiq.yml on your server. If you installed Mastodon using a different path, adjust accordingly.
2. Find the scheduler section
   Look for the scheduler: key in the YAML file. Inside it, find the entry for Scheduler::FollowRecommendationsScheduler. It looks like this:
   scheduler:
Scheduler::FollowRecommendationsScheduler:
cron: '0 /2 '
   The cron value sets the refresh interval. The example above means every 2 hours at minute 0.
3. Edit the cron expression
   Change the cron expression to your desired interval. For example, to refresh every 30 minutes, use '/30 '. To refresh every hour, use '0 '. Save the file after editing.
4. Set the FETCH_REMOTE_STATUSES environment variable
   Open your Mastodon environment file, typically /etc/systemd/system/mastodon-sidekiq.service or ~/.env.production. Add or edit the line:
   FETCH_REMOTE_STATUSES=true
   If this variable is missing or set to false, the background refresh will not run regardless of the cron schedule.
5. Restart the Sidekiq service
   Run the following command to apply changes:
   sudo systemctl restart mastodon-sidekiq
   If you use a different init system, adjust the command accordingly.
6. Verify the new schedule
   Check the Sidekiq logs to confirm the scheduler is running at the new interval. Use:
   sudo journalctl -u mastodon-sidekiq -f
   Look for lines containing FollowRecommendationsScheduler followed by a timestamp. The time between these log entries should match your new cron interval.

Common Mistakes and Performance Considerations

Setting the cron interval too short

A very short refresh interval, such as every 5 minutes, can cause excessive load on your instance and on remote servers. Each refresh cycle queues many HTTP requests to fetch statuses. If your instance follows thousands of remote accounts, a short interval can overwhelm your server’s network and CPU. Recommended minimum interval is 30 minutes for small instances and 1 hour for larger instances.

Forgetting to set FETCH_REMOTE_STATUSES to true

Even with a correct cron schedule, the background refresh will not run if FETCH_REMOTE_STATUSES is not explicitly set to true. Many administrators assume the default is enabled, but Mastodon ships with this variable unset, which means background fetching is off. Always verify this variable after changing the schedule.

Not restarting Sidekiq after config changes

Editing sidekiq.yml or the environment file does not take effect until the Sidekiq process is restarted. Some administrators edit the files and expect the changes to apply immediately. Always run the restart command to load the new configuration.

Ignoring Sidekiq queue congestion

If your Sidekiq queues are already congested with other jobs, adding more frequent federation refresh jobs can worsen performance. Monitor your Sidekiq dashboard at /sidekiq on your Mastodon instance. If the default queue has more than 100 pending jobs regularly, consider a longer refresh interval or increasing your Sidekiq worker count.

Item	Default Schedule	Recommended for Small Instances
Refresh interval	Every 2 hours	Every 30 to 60 minutes
FETCH_REMOTE_STATUSES	Unset (disabled)	Set to true
Sidekiq worker count	1-2 (depends on install)	At least 2 for refresh jobs

You can now control exactly how often your Mastodon instance refreshes content from remote servers. Start by setting a 60-minute interval and monitor your server load for a few days. If performance is acceptable, you can reduce the interval to 30 minutes for fresher content. Remember to always restart Sidekiq after any configuration change and verify the new schedule in the logs.