Troubleshooting for ONLYOFFICE Docs on Linux

Q:I cloned the code, but I find only empty folders, there is no source code.

A:The repository includes submodules. It is recommended to clone the repository executing the following command:

git clone --recursive https://github.com/ONLYOFFICE/DocumentServer.git

In case you have cloned the repository using the command:

git clone https://github.com/ONLYOFFICE/DocumentServer.git

you can update the submodules in the following way:

1. Go to the DocumentServer directory:

   cd DocumentServer

2. Run the following command:

   git submodule update --init --recursive

Q:Data loss has occurred when stopping ONLYOFFICE Docs. How to prevent data loss?

A:Due to the operational characteristic, ONLYOFFICE Docs saves a document only after the document has been closed by all the users who edited it. To avoid data loss, you must forcefully disconnect the ONLYOFFICE Docs users when you need to stop ONLYOFFICE Docs in cases of the application update, server reboot, etc. To do that, execute the following script on the server where ONLYOFFICE Docs is installed:

sudo documentserver-prepare4shutdown.sh

Q: I added a custom interface theme or updated my editor language files (corrected some translations) but the server still shows the previous values instead of the correct ones. How can I reset the cache for all the users at the same time?

A: Please follow the steps to reset the cache:

Find the /etc/nginx/includes/ds-docservice.conf and /etc/nginx/includes/ds-spellchecker.conf files. There must be the build date and time value. Change these values to some other (any value will do, but the main thing that it must be the same in all the places), and restart NGINX:

sudo service nginx reload

The cache should be reset for all the server users.

Q:ONLYOFFICE Docs services fail to start. What should I do?

A:Check the status of the services and review any error output:

sudo systemctl status ds-docservice
sudo systemctl status ds-converter

If either service has stopped, try restarting it:

sudo systemctl restart ds-docservice

Common causes include:

• Insufficient memory (at least 4 GB RAM is recommended).
• Port 80 is already in use by another application. Identify the conflicting process with sudo ss -tlnp | grep :80 and stop it, or reconfigure ONLYOFFICE Docs to use a different port.
• Check the logs for more specific error messages: /var/log/onlyoffice/documentserver/

Q:JWT authentication fails after integrating ONLYOFFICE Docs with my platform. How do I fix this?

A:Verify that the JWT secret configured in ONLYOFFICE Docs matches exactly the secret configured in your platform's connector settings. Also check that the JWT header name matches (default is "Authorization"). To check your current secret, read the configuration file directly:

cat /etc/onlyoffice/documentserver/local.json

Look for the value at services.CoAuthoring.secret.session.string. Common mistakes:

• Leading or trailing spaces in the secret value.
• Using the default random secret instead of setting a custom one.

Q:Document conversion fails (e.g., opening DOC, XLS, or PPT files shows an error). What can I do?

A:Check the converter log for errors:

cat /var/log/onlyoffice/documentserver/converter/out.log

Common causes include insufficient disk space and missing fonts.

Q:ONLYOFFICE Docs uses a lot of memory. Is this normal?

A:Memory usage scales with the number of open documents and concurrent users. For a server with a few dozen active users, 2–4 GB of RAM usage is normal. If memory usage is unexpectedly high, check for stuck or forgotten documents in /var/lib/onlyoffice/documentserver/App_Data/cache/files/forgotten/.

Q:I see a "License expired" warning. What should I do?

A:Your license.lic file has expired. Contact sales@onlyoffice.com to renew your license. After receiving the new file, replace the old license.lic file in the data directory and restart ONLYOFFICE Docs.

Q:I cannot access the Admin Panel. What should I do?

A:If you have not set up the Admin Panel yet, follow the Admin Panel setup guide. If you have forgotten your admin password, delete the passwordHash entry from runtime.json and restart — a new bootstrap code will be generated.