How to Read Mastodon Federation Errors From the Admin Dashboard

When your Mastodon server cannot communicate with other instances, content may fail to arrive in federated timelines or direct messages may not reach their destination. These failures are caused by network timeouts, SSL certificate mismatches, protocol version incompatibilities, or remote server rate-limiting. This article explains how to access and interpret federation error logs from the Mastodon admin dashboard so you can diagnose and resolve connectivity problems quickly.

What Federation Errors Tell You About Instance Health

Mastodon uses a background job system called Sidekiq to push and pull content to and from remote instances. When a federation action fails, Sidekiq stores the error message, the HTTP response code, and the timestamp. The admin dashboard surfaces these records in two main places: the Federation section and the Sidekiq logs. Understanding these errors helps you decide whether the problem is temporary, such as a network blip, or permanent, such as a domain that no longer exists.

Common error types include:

• HTTP 401 Unauthorized — The remote server rejected your instance signature. The remote admin may have blocked your domain.
• HTTP 410 Gone — The remote account or instance has been deleted.
• Net::OpenTimeout — The remote server did not respond within the timeout window, often due to firewall rules or high load.
• OpenSSL::SSL::SSLError — The remote server presented an invalid or self-signed certificate.

Mastodon does not log every failed delivery to the main dashboard by default. You must navigate to the correct admin sub-pages to see the raw error output.

Accessing Federation Error Logs in the Admin Dashboard

The admin dashboard is available only to users with the Administrator or Moderator role. Follow these steps to locate the error logs.

1. Open the Administration panel
   In the Mastodon web interface, click the hamburger menu (three horizontal lines) in the upper-right corner. Select Preferences, then click Administration in the left sidebar.
2. Go to Federation > Sidekiq
   Under Administration, click Federation. At the top of the Federation page, click the Sidekiq tab. This page shows the number of queued, retrying, and dead jobs. Dead jobs are deliveries that have exhausted all retry attempts.
3. Click on a dead job to see the error
   In the Dead Jobs section, click the job ID or the error message link. A modal window opens showing the full error backtrace, the HTTP response code, and the target URL. The target URL contains the remote instance domain and the specific API endpoint that failed.
4. Review the error class and message
   Look for the error class in the backtrace. For example, Mastodon::UnexpectedResponseError means the remote server returned an unexpected HTTP status. The error message often includes the exact HTTP code, such as HTTP 503. Copy this information for further analysis.

You can also filter jobs by queue name. The default federation queues are push (outgoing deliveries to followers on remote instances) and pull (incoming fetches from remote instances). Use the queue filter drop-down to narrow down errors to one direction.

Checking Domain Blocks That Interfere With Federation

Sometimes the error is not on the remote server but on your own. If your instance has a domain block that silences or suspends the remote domain, all federation traffic to and from that domain is stopped. To check:

1. Navigate to Administration > Federation > Domains
   Click Domains under the Federation section. The table lists all domains that have been manually blocked or limited.
2. Look for the remote domain in the list
   If the domain appears with a status of Suspended or Silenced, remove or modify the block. Click the domain name, then click Edit. Change the severity to None and save.
3. Wait for Sidekiq to retry
   After removing the block, Sidekiq will automatically retry the failed jobs within a few minutes. You can manually retry a dead job by clicking the Retry button in the Sidekiq Dead Jobs list.

If Federation Errors Persist After Checking the Dashboard

Some errors require deeper investigation beyond the admin dashboard. The following issues are common and have specific remedies.

HTTP 401 Errors That Appear Randomly

A 401 Unauthorized error means the remote server rejected the HTTP signature attached to your delivery request. This often happens when your instance changes its domain name or when the remote instance updates its allowed domains list. Verify that your instance domain is correctly set in Preferences > Administration > Server Settings > About. The domain must match the hostname used in the signature.

SSL Certificate Errors for a Single Domain

If you see OpenSSL::SSL::SSLError for one remote domain, the remote server likely has an expired or misconfigured certificate. You cannot fix the remote server, but you can instruct Mastodon to stop attempting deliveries to that domain to free up Sidekiq resources. Go to Administration > Federation > Domains, click Add new domain block, enter the domain, and choose Suspend. This stops all future delivery attempts. When the remote admin fixes the certificate, remove the block.

Sidekiq Queue Growing Unusually Large

A large queue size without visible errors in the Dead Jobs list indicates that jobs are being retried silently. Open the Sidekiq tab and look at the Retries count. Click Retries to see the list of jobs waiting for their next attempt. Each retry entry shows the same error details as a dead job. If the queue continues to grow, consider increasing the Sidekiq worker count in your deployment configuration or temporarily blocking the problematic remote domain.

Admin Dashboard vs Sidekiq Web Interface: Federation Error Visibility

Item	Mastodon Admin Dashboard	Sidekiq Web Interface
Access path	Preferences > Administration > Federation > Sidekiq	https://yourinstance.com/sidekiq (requires separate authentication)
Error backtrace visibility	Full backtrace shown in modal	Full backtrace shown in job detail page
Filter by queue	Drop-down menu for push, pull, default	Queue tabs for each named queue
Retry dead jobs	Retry button per job	Retry button per job or bulk retry
Domain block integration	Direct link to Domains page	No integration

Now you can locate federation errors in the Mastodon admin dashboard, interpret the HTTP status codes and error classes, and decide whether to retry the job, remove a domain block, or suspend a problematic remote instance. The next time a remote post fails to arrive, check the Sidekiq Dead Jobs list first. For advanced monitoring, consider enabling the Sidekiq Web UI and setting up alerts for queue size thresholds.