How to Federate Mastodon With Akkoma Fork Instances Smoothly

Mastodon users often discover that posts from Akkoma fork instances appear broken or fail to load in their federated timeline. This happens because Akkoma and its forks like Pleroma and Honk use a different federation protocol version than Mastodon. This article explains how to adjust your Mastodon server settings and client behavior so federation with Akkoma forks works reliably.

Why Mastodon and Akkoma Forks Have Federation Problems

Akkoma is a fork of Pleroma, a lightweight ActivityPub server. Akkoma and its forks implement ActivityPub version 1.0.2, while Mastodon implements version 1.0.1. The version difference causes Mastodon to reject some activities or display them incorrectly.

The most common incompatibility is in the Create object. Akkoma forks send a Create activity with a summary field for content warnings. Mastodon expects the summary field only in Note objects, not in the wrapping Create activity. This mismatch causes Mastodon to drop the post entirely or show it without the content warning.

Another difference is in media handling. Akkoma forks store media attachments under a different URL path than Mastodon. When Mastodon fetches the media URL, it gets a 404 error and shows a broken image placeholder.

Federation Protocol Version Mismatch

Mastodon uses ActivityPub 1.0.1, which defines a strict schema for activities. Akkoma forks use ActivityPub 1.0.2, which adds optional fields like source and context. Mastodon ignores unknown fields but fails when a required field is missing or in an unexpected position.

Media Attachment URL Differences

Mastodon expects media attachment URLs to follow the pattern /media/attachments/files/.... Akkoma forks use /media/... or a custom path. When Mastodon tries to proxy or cache the media, it cannot resolve the URL and shows a broken image.

Steps to Enable Smooth Federation Between Mastodon and Akkoma Forks

These steps require server admin access. If you are a user on a shared Mastodon instance, ask your admin to apply these changes.

1. Add Akkoma fork domains to the instance allowlist
   In Mastodon admin panel, go to Server > Federation > Allowlist. Enter the domain of the Akkoma fork instance, for example akkoma.example.com. Click Add. This tells Mastodon to accept activities from that domain even if the protocol version check fails.
2. Disable strict federation mode for the Akkoma fork domain
   In Mastodon admin panel, go to Server > Federation > Domain blocks. Add the Akkoma fork domain with action set to “Disable strict federation.” This setting makes Mastodon accept activities that have minor field order differences.
3. Enable the media proxy for external instances
   In Mastodon admin panel, go to Server > Media > Proxy. Enable “Proxy media from external instances.” This forces Mastodon to download and cache media from Akkoma forks, solving the 404 error caused by URL path differences.
4. Restart Mastodon services
   Run systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming on the server. This reloads the federation configuration.
5. Test federation from a Mastodon client
   Open your Mastodon client. Search for a known post from the Akkoma fork instance. If the post loads with its content warning and media, federation is working. If not, check the server logs at /var/log/mastodon/ for errors.

Client-Side Workaround for Users Without Admin Access

If you cannot change server settings, adjust your client preferences. In Mastodon web interface, go to Preferences > Federation > Strict mode and disable it. This shows posts that fail strict validation but may display them without content warnings or with broken media.

Common Federation Issues Between Mastodon and Akkoma Forks

Posts from Akkoma Fork Show “This post is unavailable”

This happens when Mastodon rejects the Create activity because the summary field is in the wrong location. The fix is to add the Akkoma fork domain to the allowlist and disable strict federation as described in steps 1 and 2 above.

Media Images from Akkoma Fork Show as Broken Links

Mastodon cannot fetch the media because the URL path does not match its expected pattern. Enable the media proxy as described in step 3. If the proxy is already enabled, clear the media cache by running systemctl restart mastodon-media-cache.

Content Warnings from Akkoma Fork Are Missing

Mastodon fails to parse the content warning from the Create activity. The post appears without the CW. Disable strict federation for the domain to accept the activity as-is. The content warning will show, but the post formatting may be slightly off.

Mastodon vs Akkoma Fork: Federation Compatibility Comparison

Item	Mastodon	Akkoma Fork
ActivityPub version	1.0.1	1.0.2
Content warning field location	Inside Note object only	Inside Create activity wrapper
Media attachment URL pattern	/media/attachments/files/...	/media/... or custom
Strict federation mode	Enabled by default	Not supported
Allowlist support	Yes	Yes

Now you can adjust your Mastodon server settings to accept activities from Akkoma fork instances. Start by adding the fork domain to the allowlist and disabling strict federation. For persistent media issues, enable the media proxy and clear the cache. As an advanced tip, monitor the Mastodon sidekiq logs with journalctl -u mastodon-sidekiq -f to see exactly which activities are being rejected and why.