Mastodon Federation Webfinger Cache TTL: How to Tune

When Mastodon instances communicate with each other, they rely on Webfinger lookups to resolve user addresses like user@example.com into local profile data. Each lookup result is cached to reduce network load and speed up subsequent requests. The default cache Time to Live (TTL) controls how long this data stays fresh before the system re-fetches it. A TTL that is too short increases outbound requests and server load. A TTL that is too long can cause stale user information to persist across the federation. This article explains what the Webfinger cache TTL does, how to adjust it in your Mastodon instance, and what side effects to expect after changing the value.

What the Webfinger Cache TTL Controls in Mastodon

Webfinger is the protocol Mastodon uses to discover a user’s ActivityPub actor endpoint from a federated address. When you search for a user on a remote instance, your local instance sends a Webfinger request to the remote instance. The remote server responds with JSON data that includes the user’s display name, avatar URL, and the location of their ActivityPub actor. Mastodon stores this response in a local cache so that subsequent searches for the same user do not require a new outbound request.

The cache TTL defines the maximum time in seconds that a cached Webfinger response remains valid. After the TTL expires, the next lookup for that user triggers a fresh Webfinger request. The cached data is not automatically refreshed in the background. It is only replaced when a new lookup occurs after the TTL has elapsed.

The default TTL is 86400 seconds, which equals 24 hours. This value works well for most Mastodon instances because user profile changes on remote instances are relatively rare. Shortening the TTL increases the number of outbound requests your instance makes, which can lead to rate limiting by remote servers or higher bandwidth usage. Lengthening the TTL reduces outbound requests but increases the chance that your instance displays outdated user information, such as an old display name or avatar.

Steps to Change the Webfinger Cache TTL

1. Open the .env.production file
   Connect to your Mastodon server via SSH. Navigate to the Mastodon installation directory, typically /home/mastodon/live. Open the .env.production file with a text editor such as nano or vim. Example command: sudo -u mastodon nano /home/mastodon/live/.env.production
2. Add or edit the WEBFINGER_CACHE_TTL variable
   Find the line that starts with WEBFINGER_CACHE_TTL. If it does not exist, add it at the end of the file. Set the value to the desired number of seconds. For a 12-hour TTL, use 43200. For a 48-hour TTL, use 172800. Example line: WEBFINGER_CACHE_TTL=43200
3. Save the file and exit the editor
   In nano, press Ctrl+O to save, then Ctrl+X to exit. In vim, press Escape, type :wq, and press Enter.
4. Restart Mastodon services
   Run the following commands to restart the Mastodon web and sidekiq processes: sudo systemctl restart mastodon-web and sudo systemctl restart mastodon-sidekiq. The new TTL value takes effect immediately after the services restart.
5. Verify the change
   Run the Mastodon Rails console to confirm the environment variable is loaded: cd /home/mastodon/live && sudo -u mastodon RAILS_ENV=production bin/rails c. Then type ENV['WEBFINGER_CACHE_TTL'] and press Enter. The console should return the new value as a string. Type exit to leave the console.

Common Mistakes and Side Effects When Tuning the TTL

Setting the TTL Too Low Causes Excessive Outbound Requests

If you set WEBFINGER_CACHE_TTL to a value below 3600 seconds (one hour), your instance will send Webfinger requests for the same remote user many times per day. Remote servers may rate-limit or block your instance if the request volume is too high. This can degrade federation performance rather than improve it. A TTL below 3600 seconds is not recommended for production instances.

Changing the TTL Does Not Clear Existing Cache Entries

The environment variable only affects new lookups. Existing cached Webfinger responses remain in the cache until their original TTL expires. To clear all cached Webfinger entries immediately, you must flush the Rails cache. Run the command: cd /home/mastodon/live && sudo -u mastodon RAILS_ENV=production bin/tootctl cache clear. This command removes all cached data, including Webfinger responses. After the flush, every lookup will fetch fresh data.

Stale User Data Persists on Federated Instances

Your own Mastodon instance only controls its own cache. Remote instances that have cached your users’ Webfinger data will continue to use their own TTL settings. Even if your instance refreshes its cache every hour, a remote instance with a 24-hour TTL will not see your user’s updated profile until its own cache expires. This is by design and cannot be overridden from your side.

Webfinger Cache TTL vs Other Federation Cache Settings

Item	Webfinger Cache TTL	Other Federation Caches
Purpose	Controls how long a user discovery result is stored locally	Controls how long ActivityPub objects and timelines are cached
Environment variable	WEBFINGER_CACHE_TTL	ACTIVITYPUB_CACHE_TTL and TIMELINE_CACHE_TTL
Default value	86400 seconds (24 hours)	300 seconds (5 minutes) for ActivityPub objects
Effect of low value	Increased outbound HTTP requests to remote instances	Higher CPU load and database queries on the local instance
Effect of high value	Stale user display names and avatars	Outdated posts in federated timelines

The Webfinger cache is separate from the ActivityPub object cache and the timeline cache. Tuning one does not affect the others. If you want to reduce overall federation load, consider adjusting all three environment variables together, but test each change separately in a staging environment first.

You can now adjust the Webfinger cache TTL on your Mastodon instance to match your federation traffic and user update frequency. Start with the default 86400 seconds and lower it only if you observe stale user data from specific remote instances. After changing the value, restart both mastodon-web and mastodon-sidekiq services. Use the tootctl cache clear command to force a full flush if you need immediate results. For advanced tuning, monitor your instance’s outbound HTTP request rate using a tool like Prometheus to find the optimal TTL for your server capacity.