Fix Matrix Synapse Federation Lag and Slow Room Joining

Start by locating the delay

When a Matrix room takes a long time to open or join, first determine whether the delay affects one remote homeserver, one room, or your entire Synapse instance. That distinction matters: federation is a two-way exchange between homeservers, and a room join can involve several servers. Slow joins may be caused by your Synapse process, the remote server, DNS or TLS routing, the database, or the room’s size and state. There is no single “federation lag” switch that fixes all of these.

Verified: Synapse records remote destination retry information, exposes Prometheus metrics, and includes rate limits for room joins. Situation-dependent: which of these is responsible for an individual slow join. Not knowable from the symptom alone: whether the other homeserver or an intermediate network is slow. Start with one affected user, one room, and the approximate time of a slow attempt; compare those details with a control room that joins normally.

Check whether federation is reachable

Use the official Matrix Federation Tester with your homeserver’s Matrix server name. It can reveal common DNS, delegation, certificate, and reachability problems. The server name in user IDs may differ from the machine or proxy that serves Synapse, so check the configured federation endpoint and delegation rather than assuming the user ID domain must host Synapse directly.

Synapse’s federation documentation describes the default federation port as TCP 8448, while delegated or reverse-proxied deployments can use HTTPS on port 443. The relevant port must be reachable from other homeservers, and outbound firewalls may also need to permit federation traffic. Check the matching inbound and outbound firewall rules, then test again from the Federation Tester. Do not open both ports indiscriminately if your deployment is configured to use only one.

A result showing a certificate, DNS, or routing error points to configuration or network reachability, not server capacity. Review the DNS records and delegation for the Matrix server name, the reverse proxy’s TLS certificate chain, and whether the proxy forwards the federation paths to Synapse. Synapse documents that a 308 permanent redirect is not followed by federating servers in some setups, so investigate unexpected redirects as well. Fix the specific failed check and retest before changing worker counts or rate limits.

Reference: Synapse federation setup and troubleshooting and Synapse firewall guidance.

See whether one remote server is in retry cooldown

Synapse temporarily marks a remote destination offline after federation requests fail. Retry delays use backoff, so repeated failures can make messages or joins involving that destination appear delayed. This is not evidence that your whole homeserver is slow: it may be a single remote server that is unreachable or failing requests.

Administrators can inspect Synapse’s Federation Admin API, which documents GET /_synapse/admin/v1/federation/destinations. Use a server-admin access token and keep it private. Review the destination records and retry fields for the homeserver involved in the affected room. These records help identify when a destination is retrying, but they do not by themselves prove why the connection failed. Correlate them with Synapse logs, proxy logs, DNS/TLS tests, and the times users reported problems.

The Federation Admin API is documented as experimental and subject to change. Avoid scripting against it as if it were a stable public client API. Synapse also documents a reset-connection-timeout operation that can prompt another background attempt for a destination already in cooldown. Treat that as a diagnostic or recovery action only after correcting or understanding the underlying failure; repeatedly clearing cooldowns cannot make an unhealthy remote server respond. A successful HTTP response from the reset endpoint does not mean the background federation attempt has already completed.

Reference: Synapse Federation Admin API. The API’s experimental status and available fields can change by Synapse release, so verify the documentation for the version you run before using an operation.

Measure Synapse and its database before scaling

Enable Synapse’s Prometheus metrics endpoint only on a trusted internal network or behind access controls. The official monitoring guide documents /_synapse/metrics and shows how to expose it through a metrics listener or an existing HTTP listener. Metrics can include operational details; do not publish this endpoint openly. If you already collect metrics, compare the time of a slow join with CPU, memory, request latency, database transaction duration, and incoming and outgoing federation activity.

Use the graphs to distinguish broad overload from federation-specific delays. If ordinary client requests and database transactions slow down at the same time as joins, inspect host CPU and memory pressure, PostgreSQL health, connection limits, disk latency, and long-running queries. If local room activity stays responsive but one remote destination has failures or retry delays, prioritize federation reachability and that remote server. If only one large room is affected, room state and the number of participating servers may contribute; compare it with a smaller room before drawing conclusions.

Synapse’s Grafana guide recommends checking message send time, CPU and memory, database transaction counts and durations, and federation graphs. A high transaction count is not automatically the bottleneck; duration and system load matter too. Check your installed Synapse version’s metric names and the current dashboard documentation because metrics have been renamed over time.

References: Synapse Prometheus monitoring and understanding Synapse through Grafana graphs.

Check room-join throttling and bursts

Synapse has separate rc_joins limits for local joins and remote joins. A remote join can require more work than joining a room the server already participates in. Synapse also has rc_joins_per_room, which limits recent joins to a room to help mitigate mass-join waves. If logs or client responses indicate rate limiting, check these settings and recent join volume before changing them.

Do not raise rate limits as a general “speed fix.” Higher limits can increase load on your server and other homeservers, and may reduce protection against join floods. If a legitimate migration or onboarding burst is hitting a configured limit, identify the exact limit and review the current documented values for your Synapse version. Consider spreading the join workload over time. Change one relevant value at a time, retain the prior configuration, and monitor error rates and resource use after reloading or restarting as required by your deployment.

Reference: Synapse configuration: rc_joins and Synapse configuration: rc_joins_per_room. Defaults and supported options can vary by release; compare them with your installed version before editing.

Use a controlled join test

1. Choose one affected room and record the room alias or room ID, the joining user’s homeserver, the time, and the exact client error. Never include access tokens in a support log.
2. Check the Federation Tester for your server name and confirm the configured federation endpoint, certificate, and proxy route.
3. Review Synapse logs around that timestamp for federation failures, remote destination errors, timeouts, or rate-limit responses. Search reverse-proxy and database logs for matching delays.
4. Inspect the Federation Admin API for retry state associated with relevant remote destinations. Compare affected rooms with a control room that joins promptly.
5. Compare Prometheus and host metrics over the same interval. Look for elevated request latency, database transaction duration, CPU, memory pressure, or a spike in federation activity.
6. Make one targeted correction—such as fixing a DNS/TLS/proxy issue, resolving a database bottleneck, or adjusting a confirmed rate-limit constraint—then repeat the same test and compare the results.

Common assumptions to avoid

• “A slow join means my server’s port 8448 is closed.” Not necessarily. Delegation or a reverse proxy may use port 443. Check the actual configured federation endpoint and test it.
• “A successful federation test proves every room join will be fast.” It only checks common federation configuration and connectivity. Remote server health, room state, local load, and database performance can still affect a join. Test the affected room and examine logs.
• “Federation lag always originates on my Synapse instance.” Synapse’s own configuration documentation cautions that observed federation delay can originate at either endpoint or in the network between them. Compare destinations and gather evidence from both ends where possible.
• “Adding workers or increasing rate limits is the first fix.” These changes are useful only when measurements point to capacity or throttling. First identify whether the problem is connectivity, remote retry, local saturation, database latency, or join rate limiting.

Verify that the fix worked

Repeat the same join test after the change. Confirm that the user joins successfully, the affected destination is no longer repeatedly failing, the Federation Tester reports the relevant checks correctly, and request/database latency returns to its normal range. Watch for recurrence during a later busy period; one successful attempt does not prove the remote server or network is consistently healthy.

If your local metrics and federation checks look healthy but only one remote homeserver continues to fail, share the timestamp, destination, sanitized error, and relevant request IDs with that server’s administrators. If several rooms and destinations are affected alongside slow local requests, investigate Synapse and PostgreSQL capacity before tuning federation behavior. Record your Synapse version with the incident notes, since configuration and Admin API details evolve.