> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

<Info>
  If you are using an earlier version please use `sharelatex` instead of `overleaf` in path names.
</Info>

<Accordion title="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:

  ```text theme={null}
  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`:

  ```yaml title="docker-compose excerpt" theme={null}
  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](https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem)
</Accordion>

<Accordion title="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:

  ```text title="Example error" theme={null}
  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](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):

  ```yaml title="config/docker-compose.override.yml" theme={null}
  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](https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting)
</Accordion>

<Accordion title="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:

  ```text title="Redis log example" theme={null}
  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](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](https://docs.overleaf.com/on-premises/support/troubleshooting#upgrading-to-redis-6.2-results-in-a-restart-loop)
</Accordion>

<Accordion title="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](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](https://docs.overleaf.com/on-premises/support/troubleshooting#incorrect-orientation-of-template-gallery-preview-thumbnail-images)
</Accordion>

<Accordion title="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:

  ```perl title="latexmkrc" theme={null}
  $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](https://docs.overleaf.com/on-premises/support/troubleshooting#please-verify-that-you-have-enabled-system-calls.-for-pdflatex-this-is-pdflatex-shell-escape)
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.