Mastodon supports custom emoji that server administrators can upload for their users. These emoji appear in the emoji picker and can be used in posts, boosts, and replies. However, custom emoji do not automatically appear on other instances when a user includes them in a post. The emoji must be federated from the origin instance to the viewing instance for others to see them correctly. This article explains how custom emoji federation works and provides the steps to ensure your emoji are visible across the fediverse.
Key Takeaways: Federating Custom Emoji Across Mastodon Instances
- Administration > Server Settings > Custom Emoji: Upload emoji to your instance to make them available to your users.
- Posting with custom emoji: When a user from another instance views a post containing your custom emoji, the emoji is fetched and cached on that instance.
- Remote emoji in local picker: Users on other instances cannot use your custom emoji in their own posts unless their admin manually adds them.
How Custom Emoji Federation Works in Mastodon
Custom emoji in Mastodon are small image files typically in PNG format. An administrator uploads these images through the administration panel and assigns each a shortcode — a name like :blobcat: that users type to insert the emoji. When a user on the origin instance includes a custom emoji in a post, the emoji shortcode is included in the post’s HTML content. Other instances that receive the post via federation see the shortcode and attempt to fetch the emoji image from the origin instance.
The federation process works through ActivityPub, the protocol that Mastodon uses to communicate between instances. When a remote instance processes a post containing a custom emoji, it checks its own emoji cache. If the emoji is not present, the remote instance makes an HTTP request to the origin instance to download the emoji file. The emoji is then stored in the remote instance’s cache and displayed in the post. This caching happens automatically and does not require administrator intervention on the remote instance.
What Gets Federated and What Does Not
Only the emoji image file and its shortcode are federated. The emoji is not added to the remote instance’s emoji picker. A user on another instance can see the emoji in a post but cannot use it in their own posts unless their administrator manually adds it to the local emoji set. The emoji is also not searchable in the remote instance’s emoji picker. This limitation is by design to prevent instances from being flooded with emoji from other servers without administrator control.
Steps to Ensure Custom Emoji Federate Correctly
To make custom emoji visible to users on other instances, the origin instance must be reachable and the emoji must be properly configured. Follow these steps to verify and troubleshoot federation.
- Upload the custom emoji on your instance
Log in to your Mastodon administration panel. Navigate to Administration > Server Settings > Custom Emoji. Click the Upload button and select your emoji image file. Enter a shortcode without colons — for example, enterblobcatfor:blobcat:. Click Save. The emoji is now available to all users on your instance. - Post a test message using the custom emoji
Create a new post on your instance. Open the emoji picker and select the custom emoji you uploaded. Alternatively, type the shortcode manually between colons. Post the message. This message will be sent to followers on other instances. - Check that your instance is publicly reachable
Federation requires that other instances can make HTTP requests to your instance. Use a tool likecurlor an online service to verify that your instance responds on port 443. If your instance is behind a firewall or uses a reverse proxy, ensure that the custom emoji endpoint is accessible. The endpoint URL ishttps://yourinstance.example.com/custom_emoji/. - Verify that remote instances can fetch the emoji
Ask a user on another instance to view your test post. If the emoji appears as a small image, federation is working. If the emoji appears as a broken image or the shortcode is displayed as plain text, the remote instance could not fetch the emoji. Check your server logs for errors related to emoji fetching. - Check the emoji file size and format
Mastodon accepts PNG and GIF formats. The maximum file size is 256 KB. Larger files may be rejected by the upload system or fail to load on remote instances. Resize your emoji to 48×48 pixels for consistent display. Use an image editor to ensure the file is under the size limit.
Common Federation Issues and How to Resolve Them
Custom Emoji Shows as Broken Image on Remote Instances
A broken image indicates that the remote instance could not download the emoji file. This often happens when the origin instance blocks requests from certain IP ranges or uses a self-signed SSL certificate. Ensure your SSL certificate is valid and issued by a trusted certificate authority. Also verify that your server’s firewall does not block incoming connections from fediverse instances. Check your web server logs for 403 or 404 errors on the emoji endpoint.
Custom Emoji Appears as Plain Text Shortcode
When a remote instance displays the shortcode as text, it means the instance could not resolve the emoji shortcode to an image. This can occur if the remote instance runs an older version of Mastodon that does not support custom emoji federation. Ask the remote instance administrator to update Mastodon to version 3.0 or later. Another cause is that the emoji shortcode contains characters that are not allowed — use only lowercase letters, numbers, and underscores.
Remote Users Cannot Use Your Custom Emoji in Their Posts
This is expected behavior. Custom emoji are not added to the emoji picker on remote instances. Only the instance that uploaded the emoji can offer it in the picker. If you want users on another instance to use your emoji, ask the administrator of that instance to manually add the emoji to their own custom emoji set. They can download the emoji file from your instance and upload it through their administration panel.
Mastodon Custom Emoji Federation vs Manual Emoji Sharing
| Item | Automatic Federation | Manual Sharing |
|---|---|---|
| Visibility in posts | Emoji appears in posts from the origin instance | Emoji appears in posts from the origin instance |
| Availability in emoji picker | Only on the origin instance | On every instance that manually adds the emoji |
| Administrator effort | None on remote instances | Remote administrators must upload the emoji |
| Cache duration | Cached until the remote instance clears its cache | Permanent once uploaded |
Custom emoji federation is the automated process where emoji images are fetched and displayed in posts on remote instances. Manual sharing requires administrators to upload the emoji to their own instance. Federation offers convenience for viewing but not for reuse. Manual sharing gives full control but requires coordination between instance administrators.
Conclusion
Custom emoji federation allows users on different Mastodon instances to see emoji from your server in posts. The process is automatic once you upload the emoji and post a message containing it. To troubleshoot federation issues, verify your server’s SSL certificate, file size, and network accessibility. For advanced control, consider setting up a shared emoji pack that administrators can download and add to their own instances. This approach gives remote users the ability to use your emoji in their own posts while keeping administration within each instance.