Mastodon Instance Disk Full From Media Cache: Cleanup Steps

If your Mastodon instance suddenly stops serving images, videos, or new posts, a full disk caused by the media cache is often the culprit. The media cache stores all images, videos, and previews that users on your instance view from other instances. Over weeks or months, this cache can grow to tens of gigabytes, filling your server disk and causing critical services like PostgreSQL to fail. This article explains why the media cache grows, how to clean it safely using Mastodon’s built-in tools, and what to do if the cleanup does not free enough space.

Why the Media Cache Fills the Disk on a Mastodon Instance

Mastodon stores media files from remote instances in a local cache so that users on your instance can view images and videos without repeatedly fetching them from the original server. Every time a user on your instance views a post from another instance that contains an image or video, Mastodon downloads that file and stores it in public/system or an object storage bucket. Over time, this cache accumulates files that are rarely or never viewed again. The problem is compounded by Mastodon’s default retention policy: the cache never deletes old files automatically unless you configure a cleanup schedule. A single active user can cause the cache to grow by several gigabytes per month. When the disk reaches 100 percent capacity, Mastodon’s background jobs fail, new posts stop processing, and the web interface returns 500 errors.

Steps to Clean the Mastodon Media Cache Safely

1. Check current disk usage and media cache size
   Run df -h on your server to see the available disk space. Then run RAILS_ENV=production bin/tootctl media usage from your Mastodon installation directory to get a breakdown of media file sizes. This command shows total size for attachments, preview cards, and avatars.
2. Remove cached media older than 7 days
   Run RAILS_ENV=production bin/tootctl media remove --days=7. This deletes all cached media from remote instances that is older than 7 days. Adjust the number of days based on your instance’s activity level. For a busy instance, 7 days is standard. For a small private instance, 30 days may be acceptable. This command does not delete media attached to posts by your own users.
3. Remove orphaned media files
   Run RAILS_ENV=production bin/tootctl media remove-orphans. This command finds media files that exist on disk but are not linked to any status in the database. Orphans can accumulate when posts are deleted or when media uploads fail mid-process. This step can free several hundred megabytes to a few gigabytes.
4. Remove preview cards for deleted links
   Run RAILS_ENV=production bin/tootctl preview_cards remove --days=7. Preview cards are the link previews generated when users share URLs. These cards include an image thumbnail and can consume significant space. This command removes preview cards older than 7 days.
5. Verify freed space and restart services
   Run df -h again to confirm the disk usage dropped. Then restart Mastodon’s background workers with systemctl restart mastodon-sidekiq and the web service with systemctl restart mastodon-web. This ensures the cleanup is recognized and new jobs can run.

If Mastodon Still Has Disk Space Issues After Cleanup

Media cache cleanup did not free enough space

If the disk is still above 80 percent after the standard cleanup, run RAILS_ENV=production bin/tootctl media remove --days=1 to remove all cached media from remote instances older than 1 day. This is aggressive and will cause images from remote posts to reload on first view, but it recovers the most space. Combine this with RAILS_ENV=production bin/tootctl media remove-orphans again.

Log files are filling the disk, not the media cache

Run du -sh /var/log to check log file sizes. Mastodon and system logs can grow to several gigabytes. Use logrotate to compress and rotate logs daily. Edit /etc/logrotate.d/mastodon to set rotate 7 and compress. Then run logrotate -f /etc/logrotate.conf to apply immediately.

PostgreSQL WAL files are consuming disk space

Write-ahead log files in /var/lib/postgresql/14/main/pg_wal can grow if replication slots are not managed. Run du -sh /var/lib/postgresql//main/pg_wal to check size. If it exceeds 2 GB, set wal_keep_size = 512 in postgresql.conf and restart PostgreSQL. This limits the number of retained WAL segments.

You can now run the media remove and remove-orphans commands to reclaim disk space on your Mastodon instance. Schedule the standard cleanup weekly using cron with 0 3 0 cd /home/mastodon/live && RAILS_ENV=production bin/tootctl media remove --days=7. For persistent disk issues, check log files and PostgreSQL WAL directories as described above. The aggressive 1-day cleanup is a last resort that recovers nearly all cache space but forces remote media to reload for all users.