Skip to main content
If you are using an earlier version please use sharelatex instead of overleaf in path names.
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:
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
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
If you’re running Overleaf on Windows or macOS, the mongo service may fail to restart, with an error:
Example error
This can occur when MongoDB data is bind-mounted from a filesystem that does not provide its required semantics, such as a Windows-mounted directory. For Windows with WSL 2, keep the Toolkit under Ubuntu’s Linux home directory and use the default bind mounts. See the platform guide’s MongoDB checks.For a new installation that needs Docker-managed storage, the following override uses named volumes (see the MongoDB image storage guidance). On an existing installation, changing mounts does not migrate data: back up and restore the database/cache before switching, or the service will see empty volumes. Add this to config/docker-compose.override.yml, merging with any existing configuration:
config/docker-compose.override.yml
For more information see: https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting
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
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/12362Reference: https://docs.overleaf.com/on-premises/support/troubleshooting#upgrading-to-redis-6.2-results-in-a-restart-loop
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
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
These errors mean that the mongo container keeps crashing and restarting. bin/up starts MongoDB and then runs a command inside it, which fails while the container restarts. bin/docker-compose ps shows the mongo service as Restarting.To find the actual cause, read the MongoDB log:
Common causes are:
  • The CPU has no AVX support. MongoDB 5.0 and later need AVX on x86-64, and the log shows MongoDB 5.0+ requires a CPU with AVX support. In a virtual machine, set the CPU type to host so that AVX is passed through.
  • Linux kernel 6.19 to 7.0.13. MongoDB refuses to start on these kernels. See Software requirements for the workaround.
  • The data was created by an older MongoDB version. MongoDB 8.0 cannot open data from 4.4 or 5.0 directly. Upgrade one major version at a time, see Updating MongoDB.
This is expected with Ayakaleaf Pro and you can ignore it. The message is printed when OVERLEAF_IS_SERVER_PRO is not true, which is the case in the Ayakaleaf Pro image. Ayakaleaf Pro does not need this variable, so leave it unset.
Before Overleaf starts, the container runs startup checks and exits when one of them fails. The Toolkit runs it with restart: always, so Docker starts it again and the same check fails again. The startup output names the failed check:
Common causes are:
  • Missing required secrets: set OVERLEAF_INVITE_TOKEN_SECRET in config/variables.env, see Environment variables.
  • ShareLaTeX to Overleaf rebranding: the configuration still uses SHARELATEX_ variables or paths; rename them as the message says.
  • An error after Checking can connect to mongo and redis: Overleaf cannot reach MongoDB or Redis. Check bin/logs mongo and bin/logs redis.
After fixing the cause, run bin/up -d.
At every start the container runs its startup scripts one after the other, and the log names each one as *** Running /etc/my_init.d/<script>.... 910_initiate_doc_version_recovery only has work to do on instances that once ran Overleaf 5.0.1. On any other instance it prints No recovery of doc versions needed. and the start continues. Its output also goes to data/history/doc-version-recovery.log in OVERLEAF_DATA_PATH.The exit code and the end of bin/docker-compose logs --tail=100 sharelatex tell what happened:
  • Exit code 2, and the log ends with *** Init system aborted.: the container was stopped, for example by bin/stop, docker stop or Ctrl+C on bin/up. The script in the last Running line is only the one that was running at that moment, it did not fail. Start the container again with bin/up -d and let the start finish.
  • Exit code 1, and the log shows *** /etc/my_init.d/<script> failed with status <n>: that script failed, and its error is in the lines just above. If 910_initiate_doc_version_recovery failed with Detected unflushed changes while recovering doc versions, the instance ran 5.0.1 and still has unflushed edits; follow the official Doc version recovery guide.
This page is shown when your account is logged in but not allowed to open the page, for example an admin page opened by an account that is not an administrator, or a project that is not shared with you.To open the admin pages, log in with an administrator account. An existing administrator can make another account an administrator, or you can create one with the create-user --admin command, see User management. In the development environment (develop/), admin pages also need ADMIN_PRIVILEGE_AVAILABLE=true in develop/dev.env; the Ayakaleaf Pro image already sets it.
Last modified on November 5, 2026