Troubleshooting

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.

If 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 the mongo image documentation for more details). 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: https://github.com/redis/redis/issues/12362

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.