Troubleshooting

Problems seen when running Ayakaleaf Pro with Docker Desktop on macOS, and how to check them.

Initialization fails with invalid command code

bin/init reports sed: ... invalid command code when it finds the BSD sed of macOS. Put GNU sed on the PATH as in 1. Download the Toolkit and check sed --version.

A failed initialization can leave all three files in config/ with an empty OVERLEAF_INVITE_TOKEN_SECRET. Running bin/init again then reports Config files already exist. For a new installation that has never started, move the three files into a backup directory and run bin/init again. For an existing instance, keep its configuration and secrets, and do not delete its files to make bin/init run again.

MongoDB keeps restarting

Read the MongoDB logs and the kernel version of the Docker VM:

bin/docker-compose logs --tail=100 mongo
docker info --format '{{.KernelVersion}}'

If the log names the Linux kernel incompatibility, follow Check the Docker VM’s Linux kernel and run bin/up -d again. Exit code 137 alone does not prove that MongoDB ran out of memory: check the container state and the logs. For an older MongoDB problem on Docker Desktop, see also Troubleshooting.

Cannot connect to the Docker daemon

Start Docker Desktop and check the selected Docker context, see 0. Setup Docker Desktop. If docker info works but compiles cannot reach Docker, check the socket settings in config/overleaf.rc and read the clsi logs. A working Docker CLI on the Mac does not prove that the application’s socket mount is correct.

The page opens, but compiles fail

Check that the TeX Live image exists locally and matches the architecture of the Docker engine:

docker image inspect ghcr.io/ayaka-notes/texlive-full:2026.1 \
  --format '{{.Os}}/{{.Architecture}}'
bin/logs -f clsi

On Apple silicon, the image should be linux/arm64. Check that SERVER_PRO and SIBLING_CONTAINERS_ENABLED are both true, then apply changes with bin/up -d. If the logs report a missing compile directory, check Docker Desktop’s file sharing and the OVERLEAF_DATA_PATH location. Do not turn off sandboxed compiles to hide a mount failure.

Not a directory, or a bind mount is missing

A host file that an override mounts may have been deleted, or Docker may have created a directory where the file should be. Check the source path on the host, and whether the mount expects a file or a directory. Restore the configuration file before you recreate the container. An installation under /tmp can run into this after macOS removes temporary files.

Port or container name conflicts

If port 8080 is in use, choose another port in config/overleaf.rc, set OVERLEAF_SITE_URL to match, and run bin/up -d again.

The Toolkit gives its containers fixed names such as sharelatex, mongo and redis. Changing PROJECT_NAME alone does not make two Toolkit installations independent. Before you start a second instance, check docker ps -a, and use other container names in a Compose override, another port and separate data directories. Do not remove the containers or data of an existing deployment to resolve a name conflict.

The instance is unreachable after a while

The Mac probably went to sleep, or Docker Desktop was quit. See Keep the instance available.

bin/doctor says this is not Linux, or asks for a Quay login

Both warnings are expected on macOS with the public image, see 2. Familiarize yourself with the Toolkit. Check the image pulls, the service status and the compile results instead, and do not ignore other errors in the report.