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

# Troubleshooting

This page is designed to help you deal with common issues you may encounter while running your on-premises version of Overleaf.

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

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

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.

</details>

<details>

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

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](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
volumes:
  mongo-data:
  redis-data:

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

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

</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.

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

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

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

{% code overflow="wrap" %}

```bash
docker exec sharelatex /bin/bash -c "mogrify -rotate 90 /var/lib/overleaf/data/template_files/6645d346c224815e9460a695_*{thumbnail,preview}"
```

{% endcode %}

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.

</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, and all things considered, it is the safer default option for this particular type of installation.

Should you wish, you can enable this for pdflatex by creating a **latexmkrc** file in the root of your project with the content `$pdflatex = 'pdflatex --shell-escape';` and then try recompiling.

</details>