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

# Probleemoplossing

> Diagnosticeer de integratie van Docker Desktop, het opstarten van MongoDB, toegang tot localhost vanuit Windows en sandbox-compilaties op WSL 2.

Voer Toolkit- en Docker-commando's uit in **Ubuntu**, tenzij ze zijn gemarkeerd met **PowerShell**. Behoud de configuratie en gegevens terwijl je fouten diagnosticeert.

### WSL of Docker meldt dat virtualisatie niet beschikbaar is

De WSL 2-backend heeft hardwarevirtualisatie en **Virtual Machine Platform** nodig, niet de volledige Hyper-V-functie die door de alternatieve Hyper-V-backend van Docker wordt gebruikt. Begin met deze controles:

1. Controleer in Windows onder **Taakbeheer → Prestaties → CPU** of **Virtualisatie: Ingeschakeld** wordt getoond. Als die is uitgeschakeld, schakel dan Intel VT-x/VMX of AMD-V/SVM in BIOS/UEFI in volgens de instructies van de fabrikant van je pc.
2. Controleer in **PowerShell als administrator** de Windows-onderdelen:

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

Als vereiste onderdelen zijn uitgeschakeld, schakel ze dan in en start Windows opnieuw op voordat je WSL opnieuw probeert:

```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. Als de onderdelen en de BIOS-instelling zijn ingeschakeld maar fout `0x80370102` blijft, controleer dan in **PowerShell als administrator**:

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

Als dit expliciet `Off` meldt, herstel dan het opstarten van de hypervisor en start Windows opnieuw op:

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

4. Als Windows zelf in een VM draait, moet de buitenste hypervisor **geneste virtualisatie** beschikbaar stellen. Alleen een selectievakje in Windows inschakelen kan ontbrekende virtuele CPU-functies niet leveren.

Volg de [herstelhandleiding van Microsoft voor WSL-fout 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) en de [probleemoplossing van Docker voor virtualisatie](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working) voor de bijbehorende fout. Deze herstelacties wijzigen Windows-onderdelen of de opstartconfiguratie; voer alleen de acties uit die relevant zijn voor jouw diagnose.

### Docker Desktop heeft een update nodig of kan geen images ophalen

Voer bij **WSL update required** `wsl --update` uit in PowerShell, start Windows opnieuw op als daarom wordt gevraagd, en open daarna Docker Desktop en Ubuntu opnieuw. Als de rij van Ubuntu nog steeds WSL 1 aangeeft, converteer de distributie dan zoals beschreven in stap 0.

Controleer bij time-outs van de registry, DNS-, proxy- of certificaatfouten welke registry precies faalt in de uitvoer van het ophalen. Configureer de proxy en het certificaatvertrouwen van Windows/Docker Desktop als je netwerk die nodig heeft; schakel TLS-verificatie niet uit. Een geslaagde GitHub-kloon bewijst niet dat Docker `ghcr.io` of Docker Hub kan bereiken. Zie de [proxy-instellingen van Docker Desktop](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). Zodra de verbinding werkt, voer je `bin/up -d` opnieuw uit; de geconfigureerde imagenamen moeten consistent blijven.

### Docker is niet beschikbaar in Ubuntu

Als `docker` niet wordt gevonden, open dan Docker Desktop in Windows, schakel Ubuntu in onder **Settings → Resources → WSL Integration**, pas de wijziging toe en open Ubuntu opnieuw. Controleer de naam en WSL-modus van de distributie met `wsl --list --verbose` in **PowerShell**. Die moet WSL 2 gebruiken.

Als de client bestaat maar de daemon niet kan bereiken, controleer dan of de engine volledig is gestart. Bekijk `docker context ls` en eventuele aangepaste `DOCKER_HOST`/`DOCKER_CONTEXT`-instellingen; een externe engine of een oude Engine-socket in Ubuntu is niet de lokale Desktop-opzet van deze handleiding. Los dit niet op door een andere daemon te installeren of de socket voor iedereen schrijfbaar te maken.

### MongoDB start niet

`bin/up` initialiseert de replica set van MongoDB voordat de applicatie start. Als het stopt bij `Waiting for Mongo...`, bekijk dan de database in een tweede **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}}'
```

Als `mongo` ontbreekt en de uitvoer een fout bij het ophalen van de image toont, los dan eerst de toegang tot de registry of het gebrek aan schijfruimte op; het opstarten van de database is dan nog niet bereikt. Zodra de oorzaak is verholpen, voer je `bin/up -d` opnieuw uit.

| Aanwijzing | Wat je controleert |
| - | - |
| `OOMKilled=true` | Vergroot het geheugen dat beschikbaar is voor WSL/Docker of verminder andere workloads, en probeer het daarna opnieuw |
| `No space left on device` | Controleer de opslag van de Windows-host, `df -h` in Ubuntu en het schijfgebruik van Docker; maak ruimte vrij zonder live databasegegevens te verwijderen |
| Rechten- of opslagfouten onder `/data/db` | Houd `MONGO_DATA_PATH` op het Linux-bestandssysteem van Ubuntu. Controleer de werkelijke bind-mount en het eigenaarschap; pas geen `chmod -R 777` toe |
| Illegal instruction / fouten over CPU-functies | Controleer of de CPU en de virtualisatie de functies beschikbaar stellen die je MongoDB-versie vereist; de poort wijzigen lost dit niet op |
| Fouten over databaseformaat / upgrade met bestaande gegevens | Volg de ondersteunde [upgradeprocedure](https://ayakaleaf-pro.mintlify.site/nl/on-premises/maintenance/upgrading-your-deployment.md); laat geen willekeurige oudere MongoDB-image naar nieuwere gegevens wijzen |

Controleer de replica set wanneer MongoDB draait:

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

Het resultaat moet `1` zijn. `bin/up -d` voert de initiële configuratie van de replica set uit; door Compose-services op een nieuwe deployment rechtstreeks te starten, sla je die stap van de Toolkit over.

Pas een MongoDB-kernelworkaround alleen toe als je Docker-engine een getroffen kernel gebruikt. Als de MongoDB-logs op een kernelprobleem wijzen, vergelijk dan de werkelijke kernel van de engine met de [productienotities van MongoDB](https://www.mongodb.com/docs/manual/administration/production-notes/) en werk WSL/Docker waar nodig bij. Wis `data/mongo` nooit als algemene oplossing voor opstartproblemen.

### Windows kan localhost niet openen

Test eerst in Ubuntu:

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

Test daarna in **PowerShell**:

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

Als beide mislukken, controleer dan de applicatielogs en de poortconfiguratie. Als alleen Windows mislukt, controleer dan of een ander Windows-proces poort 8080 gebruikt, of er aangepaste WSL-netwerkinstellingen, VPN-/proxyregels of beveiligingssoftware actief zijn. Schakel de firewall niet globaal uit. Een gewijzigde poort vereist overeenkomende waarden voor `OVERLEAF_PORT`, `OVERLEAF_SITE_URL` en de browser-URL, gevolgd door `bin/up -d`.

### Sandbox-compilaties mislukken

Controleer alle drie de onderdelen: de image bestaat in deze Docker-engine, de applicatie kan de engine-socket gebruiken, en de sibling-container kan de compilatiemap mounten:

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

Gebruik de image die is geconfigureerd in `config/variables.env`. `SERVER_PRO=true`, `SIBLING_CONTAINERS_ENABLED=true` en `DOCKER_SOCKET_PATH=/var/run/docker.sock` horen in `config/overleaf.rc`. Voer na wijzigingen `bin/up -d` uit; `bin/start` alleen werkt de omgeving van de container niet bij.

Een `No such image`-fout betekent dat Docker de exacte image die dat project vraagt niet kan vinden. Houd `TEX_LIVE_DOCKER_IMAGE` en `ALL_TEX_LIVE_DOCKER_IMAGES` consistent, haal de image op in dezelfde engine en controleer de TeX Live-selectie van het project. Bestaande projecten kunnen een oudere imagekeuze behouden.

Controleer bij een mountfout of een lege `/compile`-map of de Toolkit onder de thuismap van Ubuntu staat en of de integratie van Docker Desktop voor diezelfde distributie is ingeschakeld. Vervang het WSL-hostpad niet door een Windows-pad `C:\...`. De Toolkit berekent het pad voor de sibling-container op basis van `OVERLEAF_DATA_PATH`.

Een ontbrekend `ctexart.cls` of lettertype bij **basic** is een beperking van het pakket/de image. Controleer eerst het eenvoudige artikel uit [stap 6](https://ayakaleaf-pro.mintlify.site/nl/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md); gebruik een uitgebreidere image voor projecten die extra pakketten nodig hebben. Schakel sandboxing niet uit om een ontbrekend TeX-pakket op te lossen.

### Shellscripts melden CRLF-fouten

Voer de scripts uit in Ubuntu Bash. Bewerk de configuratie met LF-regeleinden. Fouten die `bash\r` of `$'\r'` noemen, betekenen meestal dat bestanden zijn geconverteerd naar Windows-CRLF. Herstel het betreffende script uit de repository of converteer de regeleinden ervan, met behoud van lokale configuratiewijzigingen.

### Containers verdwijnen na een herstart

Controleer of Docker Desktop draait en of de Ubuntu-integratie is ingeschakeld. `docker ps` toont alleen draaiende containers; bekijk ook `docker ps -a`. Als de engine een andere is dan die tijdens de installatie werd gebruikt, schakel dan terug naar de juiste context in plaats van nog een lege installatie te initialiseren.

Voer bij containers die aanwezig maar gestopt zijn `bin/start` uit en bekijk de logs. Volg [De instantie beschikbaar houden](https://ayakaleaf-pro.mintlify.site/nl/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available) voor opstarten bij aanmelding, restartbeleid en de slaapstandinstellingen van Windows.


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