> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/support/troubleshooting.md).

# Troubleshooting

{% hint style="info" %}
If you are using an earlier version please use `sharelatex` instead of `overleaf` in path names.
{% endhint %}

<details>

<summary>Running Overleaf with an NFS filesystem</summary>

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

{% code title="docker-compose excerpt" %}

```yaml
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
```

{% endcode %}

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>

</details>

<details>

<summary>Running Overleaf on Windows or macOS results in the `mongo` service not starting</summary>

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

{% code title="Example error" %}

```
Failed to start up WiredTiger under any compatibility version.
Reason: 1: Operation not permitted
```

{% endcode %}

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

{% code title="config/docker-compose.override.yml" %}

```yaml
volumes:
  mongo-data:
  redis-data:

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

  redis:
    volumes:
      - redis-data:/data
```

{% endcode %}

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

</details>

<details>

<summary>Upgrading to Redis 6.2 results in a restart loop</summary>

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:

{% code title="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
```

{% endcode %}

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>

</details>

<details>

<summary>Incorrect orientation of template gallery preview/thumbnail images</summary>

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>

</details>

<details>

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

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:

{% code title="latexmkrc" %}

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

{% endcode %}

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>

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/support/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.