O WSL ou o Docker informa que a virtualização não está disponível
O backend WSL 2 precisa de virtualização de hardware e da Virtual Machine Platform, e não do recurso Hyper-V completo usado pelo backend Hyper-V alternativo do Docker. Comece com estas verificações:- No Gerenciador de Tarefas → Desempenho → CPU do Windows, verifique Virtualização: Habilitado. Se estiver desativada, ative Intel VT-x/VMX ou AMD-V/SVM na BIOS/UEFI seguindo as instruções do fabricante do seu PC.
- No PowerShell como administrador, verifique os recursos do Windows:
- Se os recursos e a configuração da BIOS estiverem ativados, mas o erro
0x80370102persistir, verifique no PowerShell como administrador:
Off, restaure a inicialização do hipervisor e reinicie o Windows:
- Se o próprio Windows for executado em uma VM, o hipervisor externo precisa expor a virtualização aninhada. Ativar apenas uma caixa de seleção no Windows não fornece recursos de CPU virtual ausentes.
O Docker Desktop precisa de uma atualização ou não consegue baixar imagens
Para WSL update required, executewsl --update no PowerShell, reinicie o Windows se for solicitado e, em seguida, reabra o Docker Desktop e o Ubuntu. Se a linha do Ubuntu ainda indicar WSL 1, converta a distribuição conforme descrito na etapa 0.
Para timeouts de registro, erros de DNS, proxy ou certificado, verifique na saída do pull exatamente qual registro está falhando. Configure o proxy e a confiança de certificados do Windows/Docker Desktop se a sua rede precisar deles; não desative a verificação TLS. Um clone bem-sucedido do GitHub não prova que o Docker consegue acessar ghcr.io ou o Docker Hub. Consulte as configurações de proxy do Docker Desktop. Quando a conectividade funcionar, execute bin/up -d novamente; os nomes de imagem configurados devem permanecer consistentes.
O Docker não está disponível no Ubuntu
Sedocker não for encontrado, abra o Docker Desktop no Windows, ative o Ubuntu em Settings → Resources → WSL Integration, aplique a alteração e reabra o Ubuntu. Verifique o nome da distribuição e o modo do WSL com wsl --list --verbose no PowerShell. Ela deve usar o WSL 2.
Se o cliente existir, mas não conseguir acessar o daemon, verifique se o engine terminou de iniciar. Inspecione docker context ls e quaisquer configurações personalizadas de DOCKER_HOST/DOCKER_CONTEXT; um engine remoto ou um socket antigo de um Engine no Ubuntu não corresponde à configuração local com o Desktop deste guia. Não corrija isso instalando outro daemon nem tornando o socket gravável por todos.
O MongoDB não inicia
bin/up inicializa o replica set do MongoDB antes de iniciar a aplicação. Se ele parar em Waiting for Mongo..., inspecione o banco de dados em um segundo terminal do Ubuntu:
mongo não existir e a saída mostrar um erro de pull de imagem, resolva primeiro o acesso ao registro ou o espaço em disco; a inicialização do banco de dados ainda não foi alcançada. Depois de corrigir a causa, execute bin/up -d novamente.
Quando o MongoDB estiver em execução, verifique o replica set:
1. bin/up -d realiza a configuração inicial do replica set; iniciar os serviços do Compose diretamente em uma nova implantação pula essa etapa do Toolkit.
Aplique uma solução alternativa de kernel para o MongoDB somente se o seu engine do Docker usar um kernel afetado. Se os logs do MongoDB indicarem um problema de kernel, compare o kernel real do engine com as notas de produção do MongoDB e atualize o WSL/Docker conforme apropriado. Nunca apague data/mongo como correção genérica de inicialização.
O Windows não consegue abrir localhost
Primeiro, teste no Ubuntu:OVERLEAF_PORT, OVERLEAF_SITE_URL e URL do navegador correspondentes, seguidos de bin/up -d.
As compilações em sandbox falham
Verifique as três partes: a imagem existe neste engine do Docker, a aplicação consegue usar o socket do engine e o contêiner irmão consegue montar o diretório de compilação:config/variables.env. SERVER_PRO=true, SIBLING_CONTAINERS_ENABLED=true e DOCKER_SOCKET_PATH=/var/run/docker.sock pertencem a config/overleaf.rc. Após as edições, execute bin/up -d; bin/start sozinho não atualiza o ambiente do contêiner.
Um erro No such image significa que o Docker não consegue encontrar a imagem exata solicitada por aquele projeto. Mantenha TEX_LIVE_DOCKER_IMAGE e ALL_TEX_LIVE_DOCKER_IMAGES consistentes, baixe a imagem no mesmo engine e verifique a seleção do TeX Live do projeto. Projetos existentes podem manter uma escolha de imagem mais antiga.
Para um erro de montagem ou um diretório /compile vazio, confirme que o Toolkit está no diretório pessoal do Ubuntu e que a integração do Docker Desktop está ativada para essa mesma distribuição. Não substitua o caminho do host WSL por um caminho C:\... do Windows. O Toolkit calcula o caminho do contêiner irmão a partir de OVERLEAF_DATA_PATH.
A falta de ctexart.cls ou de uma fonte com a imagem basic é uma limitação do pacote/imagem. Primeiro, verifique o artigo simples da etapa 6; use uma imagem mais completa para projetos que precisam de pacotes adicionais. Não desative o sandbox para corrigir um pacote TeX ausente.
Os scripts de shell informam erros de CRLF
Execute os scripts no Bash do Ubuntu. Edite a configuração com finais de linha LF. Erros que mencionambash\r ou $'\r' geralmente significam que os arquivos foram convertidos para CRLF do Windows. Restaure o script afetado a partir do repositório ou converta seus finais de linha, preservando as alterações locais de configuração.
Os contêineres desaparecem após uma reinicialização
Verifique se o Docker Desktop está em execução e se a integração com o Ubuntu está ativada.docker ps mostra apenas os contêineres em execução; inspecione também docker ps -a. Se o engine for diferente do usado durante a configuração, volte para o contexto correto em vez de inicializar outra instalação vazia.
Para contêineres presentes, mas parados, execute bin/start e inspecione os logs. Siga Manter a instância disponível para a inicialização no login, as políticas de reinicialização e as configurações de repouso do Windows.