How to Fix Mastodon ‘Custom Emoji Failed to Load’ on Federated Posts

When you browse the Mastodon federated timeline, custom emoji from other instances often appear as broken image placeholders or plain text like :blobcat:. This happens because Mastodon does not automatically fetch emoji files from remote servers. The error message “Custom Emoji Failed to Load” indicates that your local instance cannot retrieve or display the emoji image file from the origin server. This article explains why this occurs and provides clear steps to fix the issue on your own Mastodon server.

Why Custom Emoji Fail to Load on Federated Posts

Mastodon stores custom emoji as small image files on each instance. When a user from a remote instance posts a custom emoji, your local server must download that emoji file from the origin server and cache it locally. This process runs as a background job in Sidekiq. If the download fails, the emoji shows as a broken image or as plain shortcode text.

Common reasons for the failure include:

Media Cache Expiration

Mastodon’s default media cache retention period is 7 days. After that, cached emoji files are deleted. When a federated post references an emoji that was cached more than 7 days ago, the server must re-download it. If the origin server is offline or slow, the download fails.

Stalled Background Jobs

Sidekiq queues handle emoji downloads. If a queue becomes stuck due to memory pressure or a corrupted job, new emoji downloads never complete. The emoji remains in a pending state and never appears on the post.

Domain Block or Server Timeout

If your instance blocks the remote domain (even partially), or if the remote server is unreachable due to network issues, the emoji file cannot be fetched. This often happens with small or poorly maintained instances.

Steps to Fix Custom Emoji Loading on Federated Posts

Follow these steps in order. Perform the first two steps from the Mastodon admin interface. Steps 3 and 4 require SSH access to your server.

Step 1: Extend Media Cache Retention Period

1. Open Administration > Server Settings
   Log in as an admin. Click Preferences in the top right, then select Administration from the left menu. Click Server Settings.
2. Go to Content Retention
   In the Server Settings page, click the Content Retention tab. This tab controls how long media files are kept.
3. Set Media Cache Retention to 30 days or more
   Find the Media cache retention period field. Change the value from 7 to 30. For busy instances, set it to 60. Click Save changes.

Step 2: Clear Media Cache Manually

1. Open Administration > Server Settings > Content Retention
   Follow the same path as Step 1.
2. Click Clear Media Cache
   Scroll down to the Clear media cache section. Click the button labeled Clear media cache now. This deletes all cached media files, including emoji. Mastodon will re-download them on the next request.

Step 3: Restart Sidekiq Queues via SSH

1. SSH into your Mastodon server
   Open a terminal. Run ssh youruser@yourserver.com. Enter your password or use your SSH key.
2. Switch to the Mastodon user
   Run su - mastodon. This ensures you run commands with the correct permissions.
3. Restart Sidekiq
   Run systemctl --user restart sidekiq. This stops and starts all Sidekiq processes. Wait 10 seconds, then check the queue status with systemctl --user status sidekiq. Look for active (running).

Step 4: Manually Trigger Emoji Re-download via Rails Console

1. Open Rails console
   While SSHed into the server as the mastodon user, run RAILS_ENV=production bin/rails c. This opens an interactive Ruby environment for the Mastodon app.
2. Find and purge stale emoji cache entries
   At the Rails prompt, type: CustomEmoji.where.not(domain: nil).where(image_file_name: nil).destroy_all. Press Enter. This deletes all cached emoji records that have no image file attached. Type exit to leave the console.
3. Restart Sidekiq again
   Run systemctl --user restart sidekiq to force Mastodon to re-download the purged emoji.

If Mastodon Still Has Issues After the Main Fix

Custom Emoji Still Shows as Broken Image on Specific Posts

If only certain federated posts have broken emoji, the origin server may be permanently offline. You cannot fix this from your instance. The emoji will never load unless the remote admin restores their server. In this case, ask your users to reload the post after 24 hours. If the issue persists, the emoji is lost.

Emoji Loads but Appears as a Question Mark or Blank Square

This indicates that the emoji file downloaded but the image format is unsupported. Mastodon supports PNG, GIF, and WebP. If the remote instance serves a JPEG or BMP file, Mastodon cannot display it. You cannot fix this from your instance. Contact the remote admin and ask them to convert the emoji to a supported format.

Emoji Loads on Desktop but Not on Mobile App

Third-party Mastodon mobile apps sometimes handle custom emoji differently. The official Mastodon app for iOS and Android supports custom emoji. If you use a third-party app, update it to the latest version. If the issue continues, switch to the official app.

Mastodon Custom Emoji Loading: Admin Fix vs User Workaround

Item	Admin Fix	User Workaround
Scope	Affects all users on the instance	Affects only the individual user
Effort	Requires SSH access and server commands	No server access needed
Permanence	Fixes the root cause permanently	Must be repeated after each cache clear
Example	Extend media cache retention to 60 days	Clear browser cache and reload the post
Limitation	Cannot fix emoji from permanently offline servers	Does not fix broken emoji for other users

You can now resolve the “Custom Emoji Failed to Load” error on federated posts by extending the media cache retention period and clearing stale cache entries. After applying the fixes, monitor your Sidekiq dashboard for stalled jobs. For ongoing maintenance, set a monthly reminder to check the Administration > Sidekiq page for any queues with high latency. This proactive step prevents emoji loading failures before they affect your users.