Stop Matrix Synapse Memory Crashes During Client Sync

If Matrix Synapse runs out of memory while clients synchronize, first confirm whether Linux actually killed a Synapse process, then measure memory during a normal /_matrix/client/v3/sync workload. If cache growth is the cause, make a modest cache adjustment rather than immediately forcing an extremely low limit; slow database responses can produce a request backlog that makes the problem worse.

As of October 10, 2026, the official Synapse release history lists 1.162.0 (September 29) as the latest stable release and 1.163.0rc1 as a prerelease. Updating an outdated installation is prudent, but a release number alone does not diagnose or guarantee a fix for sync-related memory exhaustion.

1. Prove that this is an out-of-memory failure

Clients showing endless syncing, a gateway error, or a disconnected session do not by themselves establish an OOM event. On a typical Linux systemd installation, check the kernel and service journal near the time the client failed:

sudo journalctl -k --since "1 hour ago" | grep -Ei 'oom|out of memory|killed process'
sudo journalctl -u matrix-synapse --since "1 hour ago" --no-pager

Look for a kernel OOM-killer message naming a Synapse or Python process, a systemd status such as oom-kill, or a Python MemoryError. These indicate different failure mechanisms: the kernel may kill a process when a host or container memory boundary is reached, whereas MemoryError can arise within Python before a system-wide OOM kill. The service name varies across packages; substitute your actual unit or container name.

Next, record host pressure and the largest processes while reproducing an ordinary sync:

free -h
ps -eo pid,rss,%mem,args --sort=-rss | head -n 12
systemctl show matrix-synapse -p MemoryCurrent -p MemoryMax

RSS is resident memory in kilobytes, not a precise measure of unique application memory; shared pages can be counted in multiple processes. On Docker, also inspect docker stats and the configured container memory limit. If PostgreSQL, Redis, and multiple Synapse workers share the host, assess their combined footprint rather than blaming the main Synapse process alone.

2. Tune cache memory conservatively

Synapse deliberately keeps recent events and room data in memory to serve sync requests quickly. Its documented caches.global_factor default is 0.5; decreasing this factor generally shrinks caches but raises the chance of more database work. The Synapse administrator FAQ warns that an excessively small cache on slow storage can create backlogged requests and even higher overall memory use.

Back up the active homeserver.yaml, check for an existing caches: block, and change only the relevant values. This is a trial configuration for an instance showing growing cache usage, not a universal tuning target:

caches:
  global_factor: 0.3
  sync_response_cache_duration: 1m

The sync-response cache setting controls how long completed /sync results stay cached; Synapse documents a 2m default. A shorter window may reduce retained responses, but may also increase work for clients with intermittent connections. Do not add a second caches: key if one already exists. If your installation sets SYNAPSE_CACHE_FACTOR in its service or container environment, that variable takes precedence over the YAML factor.

Validate the file with the Python environment used by your Synapse installation, adjusting the configuration path as needed:

python -m synapse.config -c /etc/matrix-synapse/homeserver.yaml

Only restart after validation. For Debian-style systemd packaging this is often sudo systemctl restart matrix-synapse; container deployments use their own orchestration. Check the service log immediately afterward for configuration errors. The Synapse configuration reference also documents reloading cache factors with SIGHUP, but that does not imply other settings, including sync-response retention, are reloadable. A controlled restart is clearer when changing both.

3. Check whether slow syncs are accumulating

If memory continues climbing while clients remain stuck, lowering caches further may be counterproductive. Compare the timing of rising RSS with CPU pressure, disk I/O, and database activity. A crowded host or slow PostgreSQL queries can cause more simultaneous in-flight requests, each of which may retain data until it finishes.

First verify that the database is responsive and that disk space and I/O are healthy. Production Synapse is designed for PostgreSQL rather than SQLite, as documented in the Synapse configuration reference. If this is an older SQLite-backed instance, plan a supported database migration with a tested backup; do not attempt a live database swap as an emergency memory workaround.

If you previously lowered global_factor to an extreme value and sync latency worsened, restore the earlier factor or test a moderately higher setting while watching both response times and total memory. Synapse's Synapse administrator FAQ explicitly notes that more cache can help when slow backends are causing queues. There is no safe fixed RAM target that fits every room count, federation load, and deployment layout.

For a busy multi-process deployment, identify whether the main process or a specific sync worker is growing. Workers allow client sync traffic to be distributed, but each worker also needs memory, so adding workers without additional capacity can aggravate host OOM pressure. Follow the Synapse worker documentation rather than routing client requests to arbitrary workers without the required shared configuration.

4. Consider cache autotuning only if prerequisites are met

On a system where an appropriate jemalloc setup is already supported and verified, Synapse provides cache_autotuning. It requires all three documented values—max_cache_memory_usage, target_cache_memory_usage, and min_cache_ttl—and uses cache eviction to keep cache usage around a target. The following figures are illustrative and must be sized to leave room for Python, the database, other services, and bursts of active requests:

caches:
  cache_autotuning:
    max_cache_memory_usage: 512M
    target_cache_memory_usage: 384M
    min_cache_ttl: 5m

Merge this block with existing cache settings instead of replacing them. These numbers are cache budgets, not process RSS limits; using them does not guarantee the process will stay under 512 MiB. The Synapse configuration reference requires jemalloc for this feature, and the Synapse administrator FAQ cautions that Python's allocator can interfere with jemalloc's accounting, potentially requiring PYTHONMALLOC=malloc. Because allocator preload paths and packaging vary, verify your deployment's actual library and startup environment before changing LD_PRELOAD. Do not copy an architecture-specific library path blindly.

5. Verify that synchronization is stable

After each single change, perform the same realistic client activity that previously triggered the failure: reconnect an existing client, allow an initial sync where practical, and wait through several normal incremental syncs. Record the peak RSS of all Synapse processes, swap activity, database responsiveness, and whether the kernel logs another OOM event. A brief dip immediately after restart is not evidence of a durable fix; caches naturally start cold.

If monitoring is enabled, compare process memory and request behavior over time using Synapse's metrics endpoint. The Synapse monitoring documentation explains that workers expose metrics independently and must be monitored separately; keep metrics endpoints private or protected rather than publishing internal data openly.

The change worked if clients complete sync without repeated reconnects, logs show no new memory kills, and memory settles at a sustainable level under the same workload. If OOMs persist despite healthy sync latency and carefully tuned caches, the next practical step is to increase available RAM or reduce the workload per host, using measured peak consumption rather than an arbitrary recommended server size.

Leave a Comment

Stop Matrix Synapse Memory Crashes During Client Sync

Diagnose Synapse out-of-memory failures during sync, adjust caching safely, identify request backlogs, and verify stable memory use.

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.

Put a Synapse Matrix Server Behind Cloudflare Safely

Put a Synapse Matrix Server Behind Cloudflare Safely

Route Matrix clients and federation through Cloudflare on HTTPS 443, preserve Synapse discovery, and avoid caching API traffic or breaking media uploads.

Restore Matrix Synapse Safely with a PostgreSQL Dump

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.

Run Mjölnir as a Matrix Room Moderation Bot with Docker

Run Mjölnir as a Matrix Room Moderation Bot with Docker

Set up Mjölnir with a dedicated Matrix account, encrypted management room, Docker Compose, policy list, and permission checks.

Enable Native Matrix Sliding Sync for Faster Mobile Loading

Enable Native Matrix Sliding Sync for Faster Mobile Loading

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.

Host Element Web on Nginx with a Custom Homeserver

Deploy Element Web as a static site, point it to your Matrix homeserver, add HTTPS, and configure Nginx to serve updates without stale files.

Run a Lightweight Matrix Homeserver on Raspberry Pi 4

Set up Conduit on a 64-bit Raspberry Pi 4 with persistent data, HTTPS federation, protected registration, and checks for a working homeserver.

Set Up a Custom Matrix Room Alias on Your Own Domain

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.

Set Up coturn for Reliable Matrix Voice and Video Calls

Configure coturn and Synapse with matching TURN credentials, open the required relay ports, and verify that Matrix clients can obtain relay candidates.