Resolve Synapse Federation TLS Certificate Errors
Trace Matrix federation certificate failures to the correct server, repair the TLS chain or CA trust, and verify the fix without disabling security checks.
When Matrix Synapse logs show SSL: CERTIFICATE_VERIFY_FAILED during federation, a join may stall, a remote server may reject your connection, or messages may fail to arrive. First determine which certificate is failing: a remote server’s certificate during an outbound request, or your own federation endpoint’s certificate when another server connects. Then repair the certificate chain, hostname, or trust configuration that the log and a federation test identify. Do not disable TLS verification as a general fix.
Matrix server-to-server traffic uses HTTPS, and the Matrix specification requires the destination to present a TLS certificate signed by a recognized certificate authority. A verification error usually means that the presented certificate is expired, incomplete, issued for a different hostname, or signed by a CA the connecting server does not trust. A reverse proxy can also serve the wrong certificate even when Synapse’s own configuration looks correct.
Check the Synapse log entry around the failure and note the remote server name and exact certificate error. If Synapse reports the failure while making a request to another homeserver, the remote server’s certificate or the CA trust used by your Synapse process is implicated. If other servers cannot federate with your domain, inspect your public TLS endpoint and server discovery instead.
Confirm your Matrix server name from homeserver.yaml, especially server_name. This is the domain portion of local Matrix IDs and determines how other homeservers reach you. Do not confuse it with the internal hostname of the machine or container. The current Synapse installation documentation explains that the server name is a federation identity and advises choosing it before installation.
Use the Matrix Federation Tester with your Matrix server name. It checks federation discovery and connectivity and can reveal whether the externally visible certificate or routing is failing. Fix the item it identifies before adjusting Synapse’s outbound trust settings.
From a machine that can reach your federation endpoint, inspect the TLS certificate. Replace matrix.example.org with the hostname that should present the certificate, and use your actual federation port. Port 8448 is common, but a reverse proxy or delegated server may use another port.
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org -showcerts </dev/null
The -servername option sends SNI (Server Name Indication), so a virtual-hosted proxy can choose the certificate for the requested name. Check the output for a successful verification result, then inspect the certificate’s subject and validity dates:
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org </dev/null 2>/dev/null | \
openssl x509 -noout -subject -issuer -dates -ext subjectAltName
The name used by Matrix federation must match a DNS name in the certificate’s Subject Alternative Name. Also check that the certificate is currently valid and that the endpoint sends its intermediate certificates. If you use a reverse proxy, test the public proxy address: a correct certificate file on the Synapse host does not help if the proxy serves a stale or unrelated certificate.
If the tester reports a certificate problem for your server, renew or reissue the certificate for the federation hostname and configure the public TLS endpoint to serve the complete chain. Synapse’s current configuration manual specifies that tls_certificate_path must point to a PEM certificate that includes intermediate certificates; for Certbot, use fullchain.pem, not cert.pem. Keep the private key in the separate tls_private_key_path file and protect it from public access.
When TLS terminates at Nginx, Caddy, or another reverse proxy, update the certificate and chain in that proxy’s configuration, then reload the proxy using the method appropriate to your installation. Synapse’s own TLS certificate paths may not control the certificate seen by federation peers in this arrangement. Follow the official Synapse reverse proxy documentation for the listener and proxy setup you use.
Check DNS and Matrix server discovery too. Federation may resolve your server name directly or follow a /.well-known/matrix/server delegation to a different hostname and port. The certificate must be valid for the hostname reached by that discovery route. A stale DNS record or incorrect delegation can direct peers to an endpoint presenting an unrelated certificate.
If the failing certificate belongs to a remote homeserver on a private network, confirm first that the certificate is intentionally issued by your private certificate authority (CA). Install and maintain that CA on the Synapse host when possible. Synapse also provides federation_custom_ca_list for custom CA certificates used for federation. The option expects PEM files and replaces the operating system’s supplied CA list, so include every CA your deployment needs rather than adding only one private CA blindly.
federation_custom_ca_list:
- /etc/matrix-synapse/certs/private-root-ca.pem
Set the path to a CA certificate, not the server’s private key. Ensure the Synapse process can read it, validate the YAML indentation, and restart or reload Synapse according to your deployment method. The Synapse configuration manual says this option is normally intended for private homeserver networks.
Do not set federation_verify_certificates: false to silence a public federation error. Its default is true; turning it off removes certificate verification for outbound federation and weakens protection against impersonation. The separate federation_certificate_verification_whitelist exists for narrow, specific cases such as Tor hidden services or controlled private setups, not as a substitute for repairing a public certificate. For private infrastructure, a trusted private CA is generally preferable.
If certificate dates appear invalid even though the certificate is current, verify the system clock and time synchronization on the Synapse host and any proxy. A clock that is substantially wrong can make a valid certificate appear not yet valid or expired. Also confirm that renewal automation actually updated the file served publicly; certificate renewal on disk does not guarantee that a proxy reloaded it.
After the correction, rerun the Federation Tester and repeat the connection that failed. Confirm the tester sees the expected hostname, valid dates, and a trusted chain, and check Synapse logs for new federation attempts without the certificate-verification error. If the tester passes but one remote server still fails, capture that server name, the timestamp, and the relevant sanitized log entry: its own certificate or trust environment may be the remaining problem. Do not share private keys, access tokens, or user message contents while troubleshooting.
Trace Matrix federation certificate failures to the correct server, repair the TLS chain or CA trust, and verify the fix without disabling security checks.
Route Matrix clients and federation through Cloudflare on HTTPS 443, preserve Synapse discovery, and avoid caching API traffic or breaking media uploads.
Back up Synapse with pg_dump, protect its signing key and media, and restore into a clean PostgreSQL database without reusing stale one-time keys.
Set up Mjölnir with a dedicated Matrix account, encrypted management room, Docker Compose, policy list, and permission checks.
Skip the retired proxy and configure Synapse’s built-in Sliding Sync. Check client discovery, then measure room-list loading and reconnect behavior on a compatible phone.
Deploy Element Web as a static site, point it to your Matrix homeserver, add HTTPS, and configure Nginx to serve updates without stale files.
Set up Conduit on a 64-bit Raspberry Pi 4 with persistent data, HTTPS federation, protected registration, and checks for a working homeserver.
Give a Matrix room an easy-to-share address on your domain using Element or the Matrix API, with checks for permissions, Synapse naming, and federation.
Configure coturn and Synapse with matching TURN credentials, open the required relay ports, and verify that Matrix clients can obtain relay candidates.
Set up a persistent Synapse homeserver with Docker Compose, PostgreSQL, a private config, and checks before exposing it through HTTPS.