Mastodon Federation Object Cache: How to Tune for Memory Efficiency

When your Mastodon instance grows, the federation object cache can consume excessive RAM. This cache stores remote posts, profiles, and media metadata from other instances. Without tuning, it may cause out-of-memory errors or force the server to swap heavily. This article explains what the federation object cache is, why it grows large, and how to adjust its settings for better memory efficiency.

What the Federation Object Cache Does and Why It Consumes Memory

The federation object cache stores data from remote servers that your instance has interacted with. This includes statuses, accounts, media attachments, and activity objects. When a user on your instance views a remote post, Mastodon fetches that data and caches it locally. The cache prevents repeated network requests for the same object. Without a cache, every view of a remote post would require a new HTTP request to the originating server.

The cache uses RAM to store these objects. On a busy instance that federates with many servers, the cache can grow to several gigabytes. Mastodon uses a least-recently-used eviction policy by default. When the cache reaches its size limit, it removes the least accessed objects. However, if the limit is set too high or the time-to-live is too long, old objects stay in memory and waste space.

The two main configuration knobs are CACHE_TTL and CACHE_SIZE. Both are environment variables set in the Mastodon configuration file or the systemd unit file. CACHE_TTL defines the maximum age in seconds that an object can remain in the cache. CACHE_SIZE defines the maximum number of objects the cache can hold. Tuning these values reduces memory consumption without breaking federation.

Steps to Tune the Federation Object Cache

Before making changes, check your current cache usage. Connect to your server via SSH and run the following command to see the current cache size:

redis-cli info memory | grep used_memory_human

This shows the total memory used by Redis, which includes the federation object cache. If this value is higher than 70% of your server’s RAM, tuning is recommended. The steps below assume you have root or sudo access to the Mastodon server.

1. Locate the Mastodon environment file
   The environment file is usually at /home/mastodon/live/.env.production or /etc/mastodon/mastodon.env. Open it with a text editor such as nano or vim.
2. Set the CACHE_TTL variable
   Add or modify the line: CACHE_TTL=3600. This sets the time-to-live to one hour. Shorter TTL values, such as 1800 seconds, free memory faster but increase network requests. Longer TTL values reduce network requests but consume more RAM.
3. Set the CACHE_SIZE variable
   Add or modify the line: CACHE_SIZE=5000. This limits the cache to 5,000 objects. For small instances with fewer than 1,000 active users, 2,000 objects is often enough. For larger instances, start with 10,000 and monitor memory usage.
4. Save the file and exit the editor
   If using nano, press Ctrl+O to save, then Ctrl+X to exit. If using vim, press Escape, type :wq, and press Enter.
5. Restart the Mastodon services
   Run the following commands to restart the web and streaming processes:
   systemctl restart mastodon-web
systemctl restart mastodon-streaming
   If your instance uses sidekiq, also run: systemctl restart mastodon-sidekiq
6. Verify the changes took effect
   Check the logs for any errors: journalctl -u mastodon-web -n 20. Then monitor Redis memory usage again: redis-cli info memory | grep used_memory_human. The value should decrease over the next few hours as old objects expire.

Common Mistakes and Things to Avoid When Tuning the Cache

Setting CACHE_TTL too short breaks federation reliability

If you set CACHE_TTL to 300 seconds, objects expire in five minutes. Users who scroll back more than five minutes will see broken media or missing profile information. The instance must re-fetch the data, causing delays. A TTL below 1800 seconds is not recommended for production instances.

Setting CACHE_SIZE too low causes frequent evictions

If you set CACHE_SIZE to 500 objects, the cache evicts objects rapidly. This increases load on the originating servers and slows down your users’ timeline loading. Start with a value that matches your instance’s average daily unique remote objects. You can estimate this by running redis-cli dbsize and dividing by 7 for a weekly average.

Changing environment variables without restarting services

Mastodon reads environment variables only at startup. Editing the file does not take effect until the web, streaming, and sidekiq processes restart. Skipping the restart step leaves the old cache settings active.

Ignoring Redis maxmemory policy

Even with tuned Mastodon variables, Redis itself may have a maxmemory setting that overrides the cache size. Run redis-cli config get maxmemory. If the value is 0, Redis can use all available RAM. Set a Redis maxmemory value that leaves at least 1 GB free for the operating system. For example, on a server with 8 GB RAM, set maxmemory 7gb in the Redis configuration file.

Mastodon Federation Object Cache Tuning Options Comparison

Item	Conservative Tuning	Aggressive Tuning
CACHE_TTL value	7200 (2 hours)	3600 (1 hour)
CACHE_SIZE value	20000 objects	5000 objects
Redis maxmemory	80% of server RAM	60% of server RAM
Expected memory savings	10-20% reduction	30-50% reduction
Risk of broken remote content	Low	Medium

You can now tune the Mastodon federation object cache to reduce memory usage while keeping federation reliable. Start by setting CACHE_TTL=3600 and CACHE_SIZE=5000 on a test instance first. Monitor Redis memory usage for 48 hours before applying the same values to production. For advanced tuning, combine these settings with a Redis maxmemory limit and enable the allkeys-lru eviction policy to further control memory consumption.