Troubleshooting

If you are using an earlier version please use sharelatex instead of overleaf in path names.

Running Overleaf with an NFS filesystem

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 used 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:

docker-compose excerpt

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.

For more details see: https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem

Running Overleaf on Windows or macOS results in the `mongo` service not starting

If you're running Overleaf on Windows or macOS, the mongo service may fail to restart, with an error:

Example 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: https://github.com/docker-library/docs/blob/master/mongo/content.md#where-to-store-data). 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):

config/docker-compose.override.yml

volumes:
  mongo-data:
  redis-data:

services:
  mongo:
    volumes:
      - mongo-data:/data/db

  redis:
    volumes:
      - redis-data:/data

For more information see: https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting

Upgrading to Redis 6.2 results in a restart loop

Use the docker logs redis command to output a copy of the logs.

If you see the line Fatal: Can't initialize Background Jobs, the full output will look something like this:

Redis log example

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

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: https://github.com/redis/redis/issues/12362

Reference: https://docs.overleaf.com/on-premises/support/troubleshooting#upgrading-to-redis-6.2-results-in-a-restart-loop

Incorrect orientation of template gallery preview/thumbnail images

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:

Find the template IDNavigate to your instance's template gallery (/templates/all), open an affected template, and copy the ID from the URL (for example: https://your-instance-url/templates/6645d346c224815e9460a695).Run the correction commandRun the following command from the Docker host (replace the template ID with the one you copied and update the path if appropriate):docker exec sharelatex /bin/bash -c "mogrify -rotate 90 /var/lib/overleaf/data/template_files/6645d346c224815e9460a695_*{thumbnail,preview}"

Reference: https://docs.overleaf.com/on-premises/support/troubleshooting#incorrect-orientation-of-template-gallery-preview-thumbnail-images

Please verify that you have enabled system calls. For pdflatex, this is 'pdflatex -shell-escape'.

The \write18 command is disabled by default in the Community Edition due to all compiles happening within the same sharelatex container; this is the safer default.

If you wish to enable it for pdflatex, create a latexmkrc file in the root of your project with the following content:

latexmkrc

$pdflatex = 'pdflatex --shell-escape';

Then try recompiling.

Reference: https://docs.overleaf.com/on-premises/support/troubleshooting#please-verify-that-you-have-enabled-system-calls.-for-pdflatex-this-is-pdflatex-shell-escape