Troubleshooting
This page is designed to help you deal with common issues you may encounter while running your on-premises version of Overleaf.
Last updated
Was this helpful?
This page is designed to help you deal with common issues you may encounter while running your on-premises version of Overleaf.
Last updated
Was this helpful?
This info is for v5.x and later. If you are using an earlier version please use sharelatex
instead of overleaf
in path names.
Mounting a NFS filesystem in an Overleaf container is technically possible, but it's not recommended and can result in different types of performance errors.
One common error that compiles see is:
EBUSY: resource busy or locked, unlink '/var/lib/overleaf/data/compiles/62f3d57bef7cf9005c364e75-62f3d57bef7cf9005c364e7a/.nfs573663533034825247625441'
In particular we advise against using NFS backed filesystems for ephemeral data, like the directories use for compilation data. We recommend using a local scratch disk, preferably a local SSD for the following directories:
For docker-compose
based setups, we suggest just overriding the bind-mount from NFS, which avoids changing paths in the application. Here's an example of a docker-compose
config excerpt with the use of a scratch disk that is mounted at /scratch
:
services:
sharelatex:
environment:
SANDBOXED_COMPILES_HOST_DIR: /scratch/compiles/
volumes:
- nfs:/var/lib/overleaf/data
- /scratch/cache/:/var/lib/overleaf/data/cache
- /scratch/compiles/:/var/lib/overleaf/data/compiles
- /scratch/output/:/var/lib/overleaf/data/output
- /scratch/tmp/:/var/lib/overleaf/tmp
There is no need to migrate any existing files from the NFS to their new home after the update. The LaTeX compiler can recreate all the files with a full compilation run again.
mongo
service not startingIf you're running Overleaf on Windows or macOS, the mongo
service may fail to restart, with an error:
Failed to start up WiredTiger under any compatibility version.
Reason: 1: Operation not permitted
To avoid this error, the data needs to be stored in a volume rather than a bind mounted directory (see ). To store data inside Docker volumes mounted inside the MongoDB and Redis containers, add the following to config/docker-compose.override.yml
(create this file if it doesn't exist yet):
volumes:
mongo-data:
redis-data:
services:
mongo:
volumes:
- mongo-data:/data/db
redis:
volumes:
- redis-data:/data
Use the docker logs redis
command to output a copy of the logs.
Fatal: Can't initialize Background Jobs
The full output will look something like this:
1:M 11 Feb 2024 15:19:22.609 # Server initialized
1:M 11 Feb 2024 15:19:22.609 # Fatal: Can't initialize Background Jobs.
1:C 11 Feb 2024 15:19:26.055 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
If you see the line Fatal: Can't initialize Background Jobs
, this may be related to the version of Docker currently in use. Updating to a version >=20.10.10 should resolve this issue.
For more information, see the Redis upstream issue here:
On occasion, the preview/thumbnail images generated by Server Pro can be created in the wrong orientation and require manual intervention to correct. These images are stored in /var/lib/overleaf/data/template_files/
(>= 5.0.3) and /var/lib/sharelatex/data/template_files/
(earlier).
We recommend backing up this folder before making any changes.
You'll need to follow the steps below for each affected template:
Navigate to your instances template gallery (/templates/all), open an affected template, and copy the ID from the URL (https://your-instance-url/templates/6645d346c224815e9460a695)
Run the following command from the Docker host:
docker exec sharelatex /bin/bash -c "mogrify -rotate 90 /var/lib/overleaf/data/template_files/6645d346c224815e9460a695_*{thumbnail,preview}"
In the above example, you'll need to replace the ID 6645d346c224815e9460a695
with the one from the affected template and update the path if appropriate.