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

# Fehlerbehebung

> Diagnose von Docker-Desktop-Integration, MongoDB-Start, Windows-Zugriff auf localhost und Sandboxed Compiles unter WSL 2.

Führen Sie Toolkit- und Docker-Befehle in **Ubuntu** aus, sofern sie nicht mit **PowerShell** gekennzeichnet sind. Behalten Sie Konfiguration und Daten bei, während Sie Fehler diagnostizieren.

### WSL oder Docker meldet, dass die Virtualisierung nicht verfügbar ist

Das WSL 2-Backend benötigt Hardware-Virtualisierung und **Virtual Machine Platform**, nicht das vollständige Hyper-V-Feature, das vom alternativen Hyper-V-Backend von Docker verwendet wird. Beginnen Sie mit diesen Prüfungen:

1. Prüfen Sie in Windows unter **Task-Manager → Leistung → CPU**, ob **Virtualisierung: Aktiviert** angezeigt wird. Falls deaktiviert, aktivieren Sie Intel VT-x/VMX oder AMD-V/SVM im BIOS/UEFI gemäß den Anweisungen Ihres PC-Herstellers.
2. Prüfen Sie in **PowerShell als Administrator** die Windows-Features:

```powershell theme={null}
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```

Wenn erforderliche Features deaktiviert sind, aktivieren Sie sie und starten Sie Windows neu, bevor Sie WSL erneut versuchen:

```powershell theme={null}
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
```

3. Wenn die Features und die BIOS-Einstellung aktiviert sind, der Fehler `0x80370102` aber bestehen bleibt, prüfen Sie in **PowerShell als Administrator**:

```powershell theme={null}
bcdedit /enum | findstr -i hypervisorlaunchtype
```

Wenn ausdrücklich `Off` gemeldet wird, stellen Sie den Hypervisor-Start wieder her und starten Sie Windows neu:

```powershell theme={null}
bcdedit /set hypervisorlaunchtype auto
```

4. Wenn Windows selbst in einer VM läuft, muss der äußere Hypervisor **verschachtelte Virtualisierung** bereitstellen. Das Aktivieren eines Kontrollkästchens in Windows allein kann fehlende virtuelle CPU-Funktionen nicht bereitstellen.

Folgen Sie für den jeweiligen Fehler der [Reparaturanleitung von Microsoft für den WSL-Fehler 0x80370102](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#error-0x80370102-the-virtual-machine-could-not-be-started-because-a-required-feature-is-not-installed) und der [Fehlerbehebung zur Virtualisierung von Docker](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working). Diese Reparaturen ändern Windows-Features oder die Boot-Konfiguration; führen Sie nur diejenigen aus, die für Ihre Diagnose relevant sind.

### Docker Desktop benötigt ein Update oder kann keine Images herunterladen

Bei **WSL update required** führen Sie `wsl --update` in PowerShell aus, starten Windows bei Aufforderung neu und öffnen dann Docker Desktop und Ubuntu erneut. Wenn die Zeile für Ubuntu weiterhin WSL 1 anzeigt, konvertieren Sie die Distribution wie in Schritt 0 beschrieben.

Prüfen Sie bei Registry-Timeouts, DNS-, Proxy- oder Zertifikatsfehlern in der Ausgabe des Downloads, welche Registry genau fehlschlägt. Konfigurieren Sie den Proxy und das Zertifikatsvertrauen von Windows bzw. Docker Desktop, falls Ihr Netzwerk dies erfordert; deaktivieren Sie nicht die TLS-Überprüfung. Ein erfolgreicher GitHub-Klon beweist nicht, dass Docker `ghcr.io` oder Docker Hub erreichen kann. Siehe [Proxy-Einstellungen von Docker Desktop](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). Sobald die Verbindung funktioniert, führen Sie `bin/up -d` erneut aus; die konfigurierten Image-Namen müssen konsistent bleiben.

### Docker ist in Ubuntu nicht verfügbar

Wenn `docker` nicht gefunden wird, öffnen Sie Docker Desktop in Windows, aktivieren Sie Ubuntu unter **Settings → Resources → WSL Integration**, übernehmen Sie die Änderung und öffnen Sie Ubuntu erneut. Prüfen Sie den Namen und den WSL-Modus der Distribution mit `wsl --list --verbose` in **PowerShell**. Sie muss WSL 2 verwenden.

Wenn der Client vorhanden ist, aber den Daemon nicht erreicht, prüfen Sie, ob die Engine vollständig gestartet ist. Prüfen Sie `docker context ls` und eventuelle benutzerdefinierte Einstellungen für `DOCKER_HOST`/`DOCKER_CONTEXT`; eine entfernte Engine oder ein alter Engine-Socket in Ubuntu ist nicht das lokale Desktop-Setup dieser Anleitung. Beheben Sie dies nicht, indem Sie einen weiteren Daemon installieren oder den Socket für alle beschreibbar machen.

### MongoDB startet nicht

`bin/up` initialisiert das MongoDB-Replica-Set, bevor die Anwendung gestartet wird. Wenn es bei `Waiting for Mongo...` stehen bleibt, untersuchen Sie die Datenbank in einem zweiten **Ubuntu**-Terminal:

```bash theme={null}
cd "$HOME/ayakaleaf-toolkit"
bin/docker-compose ps -a
bin/docker-compose logs --tail=150 mongo
docker inspect mongo --format 'Exit={{.State.ExitCode}} OOM={{.State.OOMKilled}} Error={{.State.Error}}'
docker info --format '{{.KernelVersion}}'
```

Wenn `mongo` fehlt und die Ausgabe einen Fehler beim Herunterladen des Images zeigt, beheben Sie zuerst den Registry-Zugriff oder den Speicherplatzmangel; der Start der Datenbank wurde dann noch nicht erreicht. Sobald die Ursache behoben ist, führen Sie `bin/up -d` erneut aus.

| Hinweis | Was zu prüfen ist |
| - | - |
| `OOMKilled=true` | Erhöhen Sie den für WSL/Docker verfügbaren Arbeitsspeicher oder reduzieren Sie andere Workloads und versuchen Sie es dann erneut |
| `No space left on device` | Prüfen Sie den Speicher des Windows-Hosts, `df -h` in Ubuntu und die Festplattennutzung von Docker; schaffen Sie Platz, ohne laufende Datenbankdaten zu löschen |
| Berechtigungs- oder Speicherfehler unter `/data/db` | Belassen Sie `MONGO_DATA_PATH` im Linux-Dateisystem von Ubuntu. Prüfen Sie den tatsächlichen Bind-Mount und die Eigentümerschaft; wenden Sie kein `chmod -R 777` an |
| Illegal instruction / Fehler zu CPU-Funktionen | Prüfen Sie, ob die CPU und die Virtualisierung die von Ihrer MongoDB-Version benötigten Funktionen bereitstellen; ein Ändern des Ports behebt dies nicht |
| Fehler zum Datenbankformat oder Upgrade bei vorhandenen Daten | Folgen Sie dem unterstützten [Upgrade-Verfahren](https://ayakaleaf-pro.mintlify.site/de/on-premises/maintenance/upgrading-your-deployment.md); richten Sie kein beliebiges älteres MongoDB-Image auf neuere Daten |

Wenn MongoDB läuft, prüfen Sie das Replica Set:

```bash theme={null}
bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'
```

Das Ergebnis sollte `1` sein. `bin/up -d` führt die anfängliche Einrichtung des Replica Sets durch; wenn Sie bei einer neuen Bereitstellung Compose-Dienste direkt starten, wird dieser Schritt des Toolkit übersprungen.

Wenden Sie einen MongoDB-Kernel-Workaround nur an, wenn Ihre Docker-Engine einen betroffenen Kernel verwendet. Wenn die MongoDB-Logs auf ein Kernel-Problem hinweisen, vergleichen Sie den tatsächlichen Kernel der Engine mit [MongoDBs Production Notes](https://www.mongodb.com/docs/manual/administration/production-notes/) und aktualisieren Sie WSL/Docker entsprechend. Löschen Sie `data/mongo` niemals als allgemeine Lösung für Startprobleme.

### Windows kann localhost nicht öffnen

Testen Sie zuerst in Ubuntu:

```bash theme={null}
bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad
```

Testen Sie dann in **PowerShell**:

```powershell theme={null}
curl.exe -I http://localhost:8080/launchpad
```

Wenn beides fehlschlägt, prüfen Sie die Anwendungslogs und die Port-Konfiguration. Wenn nur Windows fehlschlägt, prüfen Sie, ob ein anderer Windows-Prozess Port 8080 belegt, ob benutzerdefinierte WSL-Netzwerkeinstellungen, VPN-/Proxy-Regeln oder Sicherheitssoftware im Spiel sind. Deaktivieren Sie die Firewall nicht global. Ein geänderter Port erfordert passende Werte für `OVERLEAF_PORT`, `OVERLEAF_SITE_URL` und die Browser-URL, gefolgt von `bin/up -d`.

### Sandboxed Compiles schlagen fehl

Prüfen Sie alle drei Teile: Das Image existiert in dieser Docker-Engine, die Anwendung kann den Engine-Socket verwenden, und der Geschwister-Container kann das Kompilierungsverzeichnis einbinden:

```bash theme={null}
docker image inspect ghcr.io/ayaka-notes/texlive-basic:2026.1 --format '{{.Architecture}} {{.Id}}'
docker inspect sharelatex --format '{{json .Mounts}}'
bin/logs -f clsi
```

Verwenden Sie das in `config/variables.env` konfigurierte Image. `SERVER_PRO=true`, `SIBLING_CONTAINERS_ENABLED=true` und `DOCKER_SOCKET_PATH=/var/run/docker.sock` gehören in `config/overleaf.rc`. Führen Sie nach Änderungen `bin/up -d` aus; `bin/start` allein aktualisiert die Umgebung des Containers nicht.

Ein Fehler `No such image` bedeutet, dass Docker das genaue Image, das dieses Projekt anfordert, nicht finden kann. Halten Sie `TEX_LIVE_DOCKER_IMAGE` und `ALL_TEX_LIVE_DOCKER_IMAGES` konsistent, laden Sie das Image in derselben Engine herunter und prüfen Sie die TeX Live-Auswahl des Projekts. Bestehende Projekte behalten möglicherweise eine ältere Image-Auswahl.

Bei einem Mount-Fehler oder einem leeren `/compile`-Verzeichnis stellen Sie sicher, dass das Toolkit unter dem Home-Verzeichnis von Ubuntu liegt und die Integration von Docker Desktop für genau diese Distribution aktiviert ist. Ersetzen Sie den WSL-Host-Pfad nicht durch einen Windows-Pfad `C:\...`. Das Toolkit berechnet den Pfad für den Geschwister-Container aus `OVERLEAF_DATA_PATH`.

Eine fehlende `ctexart.cls` oder Schrift mit **basic** ist eine Einschränkung des Pakets bzw. Images. Prüfen Sie zuerst den einfachen article aus [Schritt 6](https://ayakaleaf-pro.mintlify.site/de/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md); verwenden Sie für Projekte, die zusätzliche Pakete benötigen, ein umfangreicheres Image. Deaktivieren Sie die Sandbox nicht, um ein fehlendes TeX-Paket zu beheben.

### Shell-Skripte melden CRLF-Fehler

Führen Sie die Skripte in Ubuntu Bash aus. Bearbeiten Sie die Konfiguration mit LF-Zeilenenden. Fehler, die `bash\r` oder `$'\r'` erwähnen, bedeuten meist, dass Dateien in Windows-CRLF konvertiert wurden. Stellen Sie das betroffene Skript aus dem Repository wieder her oder konvertieren Sie seine Zeilenenden und bewahren Sie dabei lokale Konfigurationsänderungen.

### Container verschwinden nach einem Neustart

Prüfen Sie, ob Docker Desktop läuft und die Ubuntu-Integration aktiviert ist. `docker ps` zeigt nur laufende Container; prüfen Sie auch `docker ps -a`. Wenn die Engine eine andere ist als die bei der Einrichtung verwendete, wechseln Sie zurück zum richtigen Kontext, statt eine weitere leere Installation zu initialisieren.

Bei vorhandenen, aber gestoppten Containern führen Sie `bin/start` aus und prüfen die Logs. Folgen Sie [Die Instanz verfügbar halten](https://ayakaleaf-pro.mintlify.site/de/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available) für den Start bei der Anmeldung, Restart-Richtlinien und die Windows-Energiesparmodus-Einstellungen.


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