Mastodon Migration to Akkoma: Compatibility Check Steps

You want to move your Mastodon account to an Akkoma instance but worry that features like follower migration or content federation may break. Mastodon and Akkoma both implement ActivityPub, but they differ in API endpoints, media handling, and moderation tools. This article explains the exact compatibility checks you must run before and after migration, covering account move, follower handshake, and timeline functionality.

Without these checks, you risk losing followers, missing posts in your home feed, or encountering broken media embeds. The steps below help you verify that your new Akkoma instance accepts the Mastodon move request and that your old Mastodon instance properly redirects followers. You will also learn how to test federation and media delivery between the two platforms.

By the end, you will have a clear checklist to confirm that your migration succeeded and that all core features work as expected on Akkoma.

Why Mastodon and Akkoma Differ in Migration Compatibility

Mastodon and Akkoma are both ActivityPub-based microblogging platforms, but they are not identical. Akkoma is a fork of Pleroma with its own API extensions and media pipeline. The core ActivityPub protocol ensures basic federation, but the account migration feature depends on specific Mastodon API endpoints that Akkoma may implement differently.

The Mastodon migration process works by sending a Move activity from the old account to the new account. The new account must accept that activity and then notify followers of the old account to refollow the new one. Akkoma supports the Move activity type, but it may reject or ignore the request if the alias verification step is not completed correctly.

Akkoma also handles media attachments and content warnings with slight variations. A post that renders fine on Mastodon may display with broken media or missing content warning labels on Akkoma. Checking these aspects after migration prevents confusion for your followers.

Key Technical Differences

Mastodon uses a RESTful API with OAuth tokens, while Akkoma uses the Mastodon API for compatibility but adds its own endpoints for administrative tasks. The Move activity is processed by both platforms, but Akkoma may require that the old account be explicitly aliased in its database before accepting the handshake. Some Akkoma instances disable the Move activity for security reasons, so you must confirm with your instance admin that it is enabled.

Media processing is another area of divergence. Mastodon uses libvips for image scaling, while Akkoma uses ImageMagick. This means that certain image formats or EXIF data may behave differently. Videos may transcode with different codecs, leading to playback issues on the other platform.

Steps to Verify Compatibility Before and After Migration

Follow these steps in order. Do not skip any step, as each one tests a critical part of the migration process.

1. Check if your Akkoma instance supports the Move activity
   Log into your Akkoma instance and open the instance info page. Look for the features field in the JSON response at https://your-akkoma-instance/api/v1/instance. The list must include "move" or "account_migration". If it is missing, contact your instance admin to enable the feature in the Akkoma configuration file.
2. Create the alias on your Mastodon account
   On your old Mastodon instance, go to Preferences > Account > Move to a different account. Enter the full handle of your new Akkoma account, for example @you@akkoma-instance.social. Mastodon will generate an alias file at https://your-old-mastodon-instance/@you. Do not delete this account until the migration is complete.
3. Initiate the move on your Akkoma account
   On your new Akkoma account, go to Preferences > Account > Move from a different account. Enter the full handle of your old Mastodon account. Akkoma will check for the alias file on the old account. If the alias is missing or malformed, the move will fail. Wait up to 30 minutes for the handshake to complete.
4. Verify follower count after 24 hours
   After the move, check your follower count on Akkoma. It may take up to 24 hours for all followers to refollow. If the count remains zero, the Move activity was likely rejected. Check the Akkoma logs or ask your admin to review the Move activity in the moderation panel.
5. Test federation with a Mastodon post
   Post a status on Akkoma and then search for that post from a Mastodon account on a different instance. Use the search field and paste the Akkoma post URL. If the post does not appear, federation between the two instances is blocked. Check your Akkoma instance’s federation settings and ensure that Mastodon instances are not in the reject list.
6. Test media display across platforms
   Upload an image and a short video from Akkoma. View the post from a Mastodon account. Verify that the image loads and the video plays. If media fails to load, ask your Akkoma admin to check the media proxy configuration. Mastodon expects media URLs to be proxied through the instance’s media cache, and Akkoma may serve direct URLs instead.
7. Check content warning and sensitive media labels
   Create a post with a content warning on Akkoma. View it from Mastodon. The Mastodon client should show the content warning banner. If it does not, the Akkoma instance may not be sending the spoiler_text field correctly. This is a known compatibility gap that some Akkoma versions have fixed.

If Migration or Federation Still Has Issues

Follower count stays at zero after 24 hours

The most common cause is that the Move activity was not accepted by Akkoma. Ask your Akkoma admin to check the move_activity log in the database. If the activity was rejected because the alias was not found, repeat the alias creation step on Mastodon and ensure that the old account is not set to private or suspended. Some Mastodon instances block the alias file when the account is locked, so set the account to public temporarily.

Posts from Mastodon do not appear in the Akkoma federated timeline

This indicates that the Akkoma instance is not pulling content from Mastodon. Check the Akkoma admin panel under Federation > Known instances. If the Mastodon instance is listed as “blocked” or “rejected,” remove it from the blocklist. Also verify that the Akkoma instance is not running in “restricted” mode, which only allows federation with approved instances.

Media embeds show broken images on Mastodon

Akkoma by default serves media directly from its storage backend, while Mastodon expects media to be proxied through the Mastodon media cache. If your Akkoma instance uses object storage like S3, the media URLs may be signed and expire. Configure the Akkoma media proxy to rewrite URLs with a static base URL. Set media_proxy in the Akkoma config to true and define the base_url.

Content warnings do not display on Mastodon

Akkoma versions before 2023.08 omit the spoiler_text field in some API responses. Upgrade Akkoma to the latest stable version. If the issue persists, ask your admin to check the Note object in the ActivityPub payload and ensure that summary is populated with the content warning text.

Mastodon vs Akkoma: Migration Feature Comparison

Item	Mastodon	Akkoma
Move activity support	Built-in, enabled by default	Requires explicit config setting move: true
Alias verification method	Alias file at /.well-known/webfinger	Same Mastodon API endpoint, but may require alias to be stored in local database
Media proxy	Automatic via media_cache	Optional, must be configured in media_proxy
Content warning field	Always sends spoiler_text	May omit spoiler_text in older versions
Federation blocklist	Instance-level blocklist	Instance-level blocklist plus restricted mode

After completing all checks, you can confirm that your migration from Mastodon to Akkoma is fully compatible. If any test fails, revisit the corresponding step or contact your instance admin. For ongoing compatibility, keep your Akkoma instance updated to the latest release and monitor the Mastodon API changelog for breaking changes. A useful next step is to test direct messages and custom emoji rendering between the two platforms, as these are common areas where minor differences appear.