Diagnosing Synapse Federation Queues via Admin API
When running a federated discussion community or decentralized chat server, remote instances occasionally become unresponsive or fail to exchange events. In Matrix networks, Synapse tracks communication attempts with remote homeservers and automatically throttles failing connections using exponential backoff. Server administrators can inspect, evaluate, and clear these connection queues by querying the experimental federation admin management API.
Assessing Connection Retries Across Remote Destinations
When Synapse attempts to deliver traffic to an external server and encounters a failure, it marks the destination as offline. Subsequent outbound traffic enters a cooldown period that grows longer if failures persist. To inspect the current status across all federating servers, administrators can consult the Synapse Federation Admin API documentation and issue a request to the destinations list endpoint:
GET /_synapse/admin/v1/federation/destinations
This request returns data for every homeserver your instance communicates with, whether an error has taken place or not. Notably, when an outage occurs, up to 20 minutes can elapse before an error appears in this list because an entire retry cycle must fail first. The JSON response includes a destinations array alongside a total integer count.
Deciding How to Query and Sort Destinations
Depending on whether your community server has hundreds or tens of thousands of remote destinations, you must select query parameters carefully to prevent unexpected database strain. Supported parameters include:
from: Defines the list offset, which defaults to 0. Pagination is handled by taking thenext_tokenreturned in a response and supplying it as thefromvalue in the subsequent call untilnext_tokenis omitted.limit: Sets the ceiling of returned destinations per request, defaulting to 100.order_by: Determines how results are sorted. Options includedestination(alphabetical order by name, which is the default),retry_last_ts(ordered by the timestamp of the last attempt in milliseconds),retry_interval(time until the next retry in milliseconds),failure_ts(when the server first began failing in milliseconds), andlast_successful_stream_ordering(the stream ordering of the latest successfully delivered PDU).dir: Sets the direction of the sort, usingffor forwards (the default) orbfor backwards.
A crucial database operational choice comes into play here: the underlying database only has an index on the destination column. Sorting by alternate attributes such as failure_ts or retry_interval forces unindexed lookups, which can impose substantial database load in large environments. For routine monitoring, stick to the default alphabetical sort unless you are troubleshooting a severe backlog.
Interpreting Destination Health Metrics
Once destination records are returned, you can inspect individual fields to determine the operational state of remote servers. Each destination object includes:
destination: The string domain or name of the remote homeserver.retry_last_ts: The timestamp in milliseconds of the last failed attempt. If the most recent transmission succeeded, this value is 0.retry_interval: The time in milliseconds Synapse waits before retrying communication. If retries are not active, this field reads 0.failure_ts: The timestamp in milliseconds when communication failures originally started. If errors have never occurred, this returns null.last_successful_stream_ordering: The stream ordering integer of the most recent successfully-sent PDU to this remote instance, or null if untracked.
To inspect a single instance without paginating the entire list, send a direct request to GET /_synapse/admin/v1/federation/destinations/<destination>, which returns identical destination fields for that specific host.
Investigating Room-Specific Federation Blockages
Federation failures often impact specific shared discussions while leaving others untouched. To isolate which rooms are federating with an ailing remote homeserver, administrators can query:
GET /_synapse/admin/v1/federation/destinations/<destination>/rooms
This endpoint supports from (default 0), limit (default 100), and dir (sorting forward f or backward b by room_id), alongside next_token pagination. The returned objects contain the specific room_id and the stream_ordering integer for the latest successfully delivered PDU in that shared space. Reviewing these room associations alongside your wider community setup—such as your Synapse Matrix homeserver architecture—helps determine the blast radius when a partner server goes dark.
Resetting Retries Versus Waiting Out the Cooldown
When a remote homeserver recovers from an outage, administrators face a choice: let Synapse reach the end of its exponential backoff interval, or force immediate reconnection. If the backoff period has expanded to hours or days, waiting causes long delays in event propagation.
To override the backoff timer, admins can trigger a connection reset described in the Synapse federation documentation:
POST /_synapse/admin/v1/federation/destinations/<destination>/reset_connection
Before issuing this POST request, verify the prerequisites: the remote server must have encountered an error, and retry_last_ts must not be equal to 0. Submitting this call cancels the cooldown period and prompts Synapse to initiate connection attempts in the background immediately. Note that even after receiving an HTTP 200 response, the underlying connection attempt runs as an asynchronous background task and may take some time to finish.
Sources
Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.