How to Detect Federation Breakage Between Two Instances

Federation breakage occurs when two Mastodon instances can no longer exchange posts, notifications, or direct messages. You may notice that profiles from a remote instance appear blank, posts from a specific server stop appearing in your federated timeline, or direct messages from users on that instance never arrive. The root cause is often a blocked domain, a suspended instance, or a technical failure in the ActivityPub delivery protocol. This article explains how to identify the exact point of failure between two instances using server-side tools and manual checks.

Why Federation Breakage Happens Between Two Instances

Federation in Mastodon relies on the ActivityPub protocol. Each instance maintains a list of known remote servers and periodically exchanges activities such as Create, Announce, and Like. When an instance stops receiving or sending activities to another, the breakage can be caused by one of several conditions.

The most common cause is a domain-level block. Instance admins can silence, suspend, or fully block a remote domain. Silencing hides public posts from the local timeline but still allows private interactions. Suspension removes all content from the remote server and prevents any new activities from being accepted. A full block rejects all incoming connections entirely.

Another cause is a technical failure in the delivery queue. Mastodon uses Sidekiq to process outbound activities. If the remote instance is unreachable for an extended period, Sidekiq marks the delivery as failed and stops retrying after a configurable number of attempts. The sending instance then drops the pending activities.

A third cause is a misconfigured reverse proxy or TLS certificate on either instance. If the remote server’s SSL certificate has expired or its web server returns a 5xx error, the ActivityPub handshake fails silently.

Steps to Detect Federation Breakage Between Two Instances

Follow these steps in order. You need admin access to at least one of the two instances to complete all checks. If you do not have admin access, you can still perform the public API tests in steps 3 and 4.

1. Check the local instance’s domain blocks
   Log in to your instance’s admin panel. Navigate to Moderation > Federation > Domains. Search for the remote domain name. If it appears with a status of Suspended or Blocked, federation is intentionally disabled. If it appears with Silenced, public posts are hidden but direct interactions still work.
2. Inspect the Sidekiq delivery queue
   In the admin panel, go to Moderation > Federation > Sidekiq queues. Look for the queue named push or default. If you see a large number of retries or failed jobs targeting the remote domain, the sending instance cannot deliver activities. Click on a failed job to see the error message. Common errors include Net::OpenTimeout and Net::ReadTimeout, which indicate the remote server is not responding.
3. Query the remote instance’s public API
   Open a terminal or use a tool like Postman. Send a GET request to the remote instance’s API endpoint for a known user. For example: curl https://remote-instance.example/api/v1/accounts/1. If the request returns a 200 status and a valid JSON object with an id field, the remote instance is reachable and serving API requests. If it returns a 403, the remote instance may have blocked your IP. If it returns a 502 or 503, the remote server is experiencing a backend error.
4. Test ActivityPub object delivery
   Fetch a specific post from the remote instance using its ActivityPub representation. Append .json to the post URL. For example: curl https://remote-instance.example/@username/12345.json. A valid response returns a JSON-LD document with @context and type fields. If the response is empty or returns a 404, the remote instance is not publishing that object to the public.
5. Check the remote instance’s server headers
   Run curl -I https://remote-instance.example to inspect the HTTP headers. Look for the Server header. If it shows Mastodon or a version string, the instance is running Mastodon. If it shows nginx or Apache without a Mastodon version, the reverse proxy is working but the application may be down. Also check for X-Frame-Options and Content-Security-Policy headers that might block cross-origin requests.
6. Verify TLS certificate validity
   Use openssl s_client -connect remote-instance.example:443 -servername remote-instance.example. A valid certificate chain should show Verify return code: 0 (ok). If the certificate is expired or self-signed, the TLS handshake fails and Sidekiq cannot deliver activities.

If Federation Still Appears Broken After These Tests

Posts from the remote instance appear in the federated timeline but direct messages fail

This usually indicates a silence or a per-user block rather than a domain block. Check the remote user’s profile on your instance. If their account shows a lock icon or the profile says “This account has been limited,” the local admin has silenced that specific user. Ask the local admin to review Moderation > Accounts > Limited accounts and remove the limitation if appropriate.

Outbound activities from your instance are queued but never delivered

If Sidekiq shows a growing queue of failed deliveries to the remote instance, the remote server may be rate-limiting your instance. Mastodon instances can configure rate limits in the config/initializers/rack_attack.rb file. Ask the remote admin to check their rate-limit logs. Alternatively, the remote instance may have reached its storage quota and cannot accept new activities.

Federation works intermittently — posts sometimes arrive and sometimes do not

This pattern suggests a network issue rather than a permanent block. Check the DNS resolution of the remote domain from your instance’s server. Run nslookup remote-instance.example. If the DNS response changes between multiple IP addresses, one of the IPs may be unreachable. Also check if your instance uses a CDN or proxy that caches DNS results for too long.

Item	Domain Block	Delivery Queue Failure
Description	Admin intentionally blocks or silences the remote domain	Sidekiq cannot deliver activities due to network or server error
Symptom	All content from the remote instance is hidden or rejected	Outbound activities are queued but never delivered; errors in Sidekiq
Detection method	Check Moderation > Federation > Domains	Inspect Sidekiq push queue for failed jobs
Resolution	Remove the block or silence in the admin panel	Fix the remote server’s network or TLS issue; clear the Sidekiq queue

You can now systematically identify the cause of federation breakage between any two Mastodon instances. Start with the domain block check in the admin panel, then move to the Sidekiq queue inspection, and finally perform the API and TLS tests. If the remote instance is blocking your IP, contact the remote admin and ask them to whitelist your instance’s IP address in their config/initializers/rack_attack.rb file. For persistent delivery failures, consider setting up a dedicated Sidekiq queue for each remote domain to isolate problems.