Troubleshooting

Troubleshooting

Troubleshooting Installation

Synapse requires pip 8 or later, so if your OS provides too old a version you may need to manually upgrade it:

sudo pip install --upgrade pip

Installing may fail with Could not find any downloads that satisfy the requirement pymacaroons-pynacl (from matrix-synapse==0.12.0). You can fix this by manually upgrading pip and virtualenv:

sudo pip install --upgrade virtualenv

You can next rerun virtualenv -p python2.7 synapse to update the virtual env.

Installing may fail during installing virtualenv with InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning. You can fix this by manually installing ndg-httpsclient:

pip install --upgrade ndg-httpsclient

Installing may fail with mock requires setuptools>=17.1. Aborting installation. You can fix this by upgrading setuptools:

pip install --upgrade setuptools

If pip crashes mid-installation for reason (e.g. lost terminal), pip may refuse to run until you remove the temporary installation directory it created. To reset the installation:

rm -rf /tmp/pip_install_matrix

pip seems to leak lots of memory during installation. For instance, a Linux host with 512MB of RAM may run out of memory whilst installing Twisted. If this happens, you will have to individually install the dependencies which are failing, e.g.:

pip install twisted

Running out of File Handles

If synapse runs out of filehandles, it typically fails badly - live-locking at 100% CPU, and/or failing to accept new TCP connections (blocking the connecting client). Matrix currently can legitimately use a lot of file handles, thanks to busy rooms like #matrix:matrix.org containing hundreds of participating servers. The first time a server talks in a room it will try to connect simultaneously to all participating servers, which could exhaust the available file descriptors between DNS queries & HTTPS sockets, especially if DNS is slow to respond. (We need to improve the routing algorithm used to be better than full mesh, but as of June 2017 this hasn't happened yet).

If you hit this failure mode, we recommend increasing the maximum number of open file handles to be at least 4096 (assuming a default of 1024 or 256). This is typically done by editing /etc/security/limits.conf

Separately, Synapse may leak file handles if inbound HTTP requests get stuck during processing - e.g. blocked behind a lock or talking to a remote server etc. This is best diagnosed by matching up the 'Received request' and 'Processed request' log lines and looking for any 'Processed request' lines which take more than a few seconds to execute. Please let us know at #matrix-dev:matrix.org if you see this failure mode so we can help debug it, however.

ArchLinux

If running $ synctl start fails with 'returned non-zero exit status 1', you will need to explicitly call Python2.7 - either running as:

python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml

...or by editing synctl with the correct python executable.

Help!! Synapse eats all my RAM!

Synapse's architecture is quite RAM hungry currently - we deliberately cache a lot of recent room data and metadata in RAM in order to speed up common requests. We'll improve this in future, but for now the easiest way to either reduce the RAM usage (at the risk of slowing things down) is to set the almost-undocumented SYNAPSE_CACHE_FACTOR environment variable. The default is 0.5, which can be decreased to reduce RAM usage in memory constrained enviroments, or increased if performance starts to degrade.

Using libjemalloc can also yield a significant improvement in overall amount, and especially in terms of giving back RAM to the OS. To use it, the library must simply be put in the LD_PRELOAD environment variable when launching Synapse. On Debian, this can be done by installing the libjemalloc1 package and adding this line to /etc/default/matrix-synapse:

LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1