Raise Synapse’s Systemd File Limit Without Guesswork

Illustrative scenario: Rowan administers a small Matrix homeserver and sees Synapse log [Errno 24] Too many open files when activity rises. If the running Synapse process has reached its systemd open-file limit, raise LimitNOFILE in a systemd drop-in for the affected service, reload systemd, and restart Synapse. Confirm the limit on the running process. Do not change a global kernel limit until you have evidence that the machine-wide file table is exhausted.

The exact limit depends on the installation and workload; the example value below is not an official Synapse minimum. Synapse’s current systemd guidance covers a master service, optional worker template units, and a target that groups them. Match the unit names to your own installation. See the Synapse systemd-with-workers documentation.

A terminal window shows matrix-synapse.service journal entries with repeated Errno 24 Too many open files messages.
The example journal output shows Synapse reporting Errno 24 while accepting connections. It illustrates the symptom and is not a log from a real server.

Find out which limit is failing

“Open files” means file descriptors: handles a process uses for sockets, files, pipes, and other resources. Synapse may need many descriptors for client connections, federation, database connections, and workers. First inspect the service and its logs:

sudo systemctl status matrix-synapse.service
sudo journalctl -u matrix-synapse.service -b --no-pager -n 100
sudo systemctl show matrix-synapse.service -p MainPID -p LimitNOFILE

Replace matrix-synapse.service if your unit has another name. A package, container, or custom deployment can name or launch the service differently. Use systemctl list-units '*synapse*' to find units managed by the current systemd manager. If systemd does not directly launch Synapse, this override may not control the process.

Take the MainPID from the output and inspect that process. Substitute its numeric PID for PID:

grep -i 'open files' /proc/PID/limits
ls /proc/PID/fd | wc -l

The first command shows the running process’s soft and hard limits; the second counts its currently open descriptors. If the count is near the soft limit and the log contains Too many open files or Errno 24, a per-process limit is a plausible cause. The kernel exposes these values through /proc/<pid>/limits; see the Linux process limits reference.

For Rowan’s example, suppose the process soft limit is 1,024 and the descriptor count is close to it. That supports adjusting the unit. If the process is nowhere near its limit, inspect the full error and resource usage before raising limits; a leak or a different failure may be responsible.

A terminal displays LimitNOFILE=1024 and a process limits table where the open-files soft limit is 1024 and hard limit is 524288.
The sample process limit table shows a 1,024 soft open-file limit and a higher hard limit. Check the running Synapse process instead of relying on a login shell’s ulimit.

Raise the limit with a systemd drop-in

A drop-in adds a small override without editing the package’s vendor unit. On a typical systemd installation, create the override for the actual master unit:

sudo systemctl edit matrix-synapse.service

Enter this setting in the editor:

[Service]
LimitNOFILE=65536

Save and exit. 65536 is an example, not a Synapse-prescribed value. Choose a value above observed peak use with headroom, within the host’s supported hard limit and operational capacity. systemd accepts resource-limit settings such as LimitNOFILE; its documentation also cautions that some programs using select(2) cannot handle descriptors above 1,023. Confirm the runtime and application tolerate the chosen value rather than copying it blindly. Read the systemd.exec resource-limit documentation.

Reload the unit definitions and restart Synapse so the process is relaunched with the new limit:

sudo systemctl daemon-reload
sudo systemctl restart matrix-synapse.service
sudo systemctl status matrix-synapse.service --no-pager

Do not rely on ulimit -n from your SSH session to change a system service. A login shell and a systemd service receive limits from different contexts; the service’s effective setting must be inspected directly.

A text editor shows a systemd drop-in override.conf with a Service section and LimitNOFILE=65536.
The systemd drop-in sets a service-level LimitNOFILE value. The example value is illustrative; select a limit that fits the host and application.

Apply the limit to workers and containers when needed

If you run Synapse workers, each worker is a separate service process and has its own resource limit. The official systemd example uses units such as matrix-synapse-worker@generic_worker.service. Create a matching drop-in for every active worker unit that is hitting the limit, for example:

sudo systemctl edit matrix-synapse-worker@generic_worker.service

Then add the same [Service] and LimitNOFILE lines, reload systemd, and restart the worker or the Synapse target. The Synapse documentation shows restarting the target to restart the master and its workers together. Confirm each affected unit’s effective limit individually.

For Docker or another container manager, a host systemd override only helps if that unit directly starts the process and passes the limit through. Otherwise, set the file-descriptor limit through the container runtime or orchestration configuration, then recreate/restart the container and inspect the process inside it. Synapse’s installation documentation lists its official container image; packaging details vary, so check the runtime’s current configuration instead of applying a host-only command.

A terminal shows systemd daemon reload and Synapse restart commands followed by LimitNOFILE=65536 and an active running service status.
After reloading systemd and restarting the service, the displayed effective limit is 65,536 and the Synapse unit is active in this example.

Verify Synapse is healthy

After restart, rerun systemctl show and inspect /proc/PID/limits using the new main PID. The effective soft and hard limits should reflect the configured value. Check the journal for startup failures and fresh Too many open files errors, then make a client request and confirm federation or worker activity that was affected has resumed.

If the error says Too many open files in system or logs point to the kernel file table, inspect /proc/sys/fs/file-nr: its first number is allocated file handles and its third is the maximum. A system-wide shortage is different from Synapse reaching its own descriptor limit; investigate other services and global capacity before considering kernel-level changes. The Linux proc filesystem reference documents file-nr and file-max.

For Rowan, the fix is verified only when the restarted process has the intended limit, Synapse stays active, and the original log error no longer recurs under the relevant workload. If usage keeps climbing toward the new limit, investigate descriptor leaks or capacity needs instead of repeatedly increasing the number.

Leave a Comment

Raise Synapse’s Systemd File Limit Without Guesswork

Raise Synapse’s Systemd File Limit Without Guesswork

Diagnose whether Synapse hit its per-process open-file cap, set a systemd drop-in for the right service or worker, and verify the live limit.

Element Shows “Failed to Decrypt”? Restore the Missing Room Key

Element Shows “Failed to Decrypt”? Restore the Missing Room Key

Find out whether the error is limited to one browser or one event, then use Element’s recovery key or a trusted device without risking your remaining encrypted history.

Clean Up Old Synapse Messages and Media Without Losing Data

Use Synapse’s history and media purge APIs or retention settings to remove stale data safely, then verify completion and disk-space recovery.

Build a Matrix Echo Bot in Python with Simple-Matrix-Bot-Lib

Build a Matrix Echo Bot in Python with Simple-Matrix-Bot-Lib

Install the current library, connect a dedicated Matrix account, and run a small !echo bot with safer credential handling and a clear test.

Connect Matrix to WhatsApp, Telegram, and Discord with Separate Bridges

Connect Matrix to WhatsApp, Telegram, and Discord with Separate Bridges

Set up three mautrix bridges with separate registrations, logins, and tests—and avoid Docker networking, account-policy, and sync surprises.

Reclaim Synapse Media Disk Space Without Breaking Shared Files

Find what is filling Synapse storage, set safe media retention, and purge remote cache without deleting files directly from disk.

Deactivate Inactive Matrix Users Without Deleting Room History

Deactivate Inactive Matrix Users Without Deleting Room History

Review device activity, deactivate confirmed inactive Synapse accounts through the Admin API, and learn what the optional erase flag actually removes.

Reduce PostgreSQL Memory Pressure in Matrix Synapse

Find whether PostgreSQL memory comes from query work, shared buffers, connections, or maintenance, then make targeted Synapse-safe changes.

Why Matrix Synapse Room Joins Are Slow—and What to Check

Why Matrix Synapse Room Joins Are Slow—and What to Check

Trace slow Matrix room joins to one remote homeserver, federation backoff, local database load, or an outbound sender queue before changing Synapse settings.

Close Matrix Sign-Ups or Require Invite Tokens on Synapse

Stop open account creation on a self-hosted Synapse server, or keep sign-ups invite-only with limited-use registration tokens.