# Troubleshooting

| Sintoma | Causa provável | Solução |
|---|---|---|
| `docker: command not found` | Docker não instalado | [installation.md](installation.md#windows-instalando-o-docker-desktop) |
| `required variable POSTGRES_PASSWORD is missing` | `.env` ausente/incompleto | `./scripts/bootstrap-local.sh` |
| `ALLOW_TARGETS ... relay aberto` no compose | `WS_ALLOW_TARGETS` vazio | defina no `.env` (ver `.env.example`) |
| `openmu` fica `starting` vários minutos | 1ª inicialização populando o banco Season 6 | normal (até ~5 min); acompanhe `scripts/logs.sh openmu` |
| `openmu` unhealthy, log com `Npgsql ... password authentication failed` | senha do Postgres trocada depois do volume criado | a senha só vale na criação do volume. Volte a senha antiga **ou** (perde dados!) `docker compose down -v` |
| Admin pede login e não sei a senha | bootstrap user | `OPENMU_ADMIN_USER`/`OPENMU_ADMIN_PASSWORD` no `.env` (sessões persistem no volume `adminpanel-keys`) |
| `play.localhost` não abre | navegador/OS não resolve `*.localhost` | use Chrome/Edge/Firefox atuais, ou adicione `127.0.0.1 play.localhost ws.localhost admin.localhost docs.localhost` ao arquivo hosts |
| Página do jogo abre mas não conecta | `VITE_WS_*` do build não batem com a URL real | rebuild do `web-client` após ajustar `WEB_WS_URL`/`WEB_WS_PORT`; ou teste `?ws=ws://ws.localhost:80` |
| Web: erro 403 no WebSocket | alvo fora de `ALLOW_TARGETS` (ex. servidor 3+ ou IP público anunciado) | inclua `openmu:<porta>` no `WS_ALLOW_TARGETS`; confirme política `gs=cs` (`?gs=cs`) |
| Web: login falha com senha longa | senha acima de 20 caracteres (limite do `LoginLongPassword`) | use senha ≤ 20 |
| Muitos jogadores web: "Maximum Connections per IP reached" | todos chegam com o IP do proxy (padrão 30) | `./scripts/set-connection-limit.sh` (teto do CS 44406, padrão 1000; reinicia o openmu) |
| WebSocket do jogo recusado com **429** | limite por IP real no Traefik (`ws-per-ip`, D20) — muitas abas/jogadores atrás do mesmo IP | aumente `WS_MAX_CONN_PER_IP` no `.env` e `docker compose up -d reverse-proxy` |
| Mudei um arquivo de `infra/traefik/dev/` ou `dynamic/` e o Traefik não aplicou | arquivo montado individualmente: editores que trocam o arquivo (sed -i) quebram o watch | `docker compose restart reverse-proxy` |
| Certificado não emite (prod) | DNS não propagou / porta 80 fechada | `dig play.DOMINIO`; `ufw status`; logs do `reverse-proxy` |
| WebSocket cai após ~60 s | timeout de leitura do entrypoint | já configurado `respondingTimeouts.readTimeout=0s`; verifique proxies/CDN na frente |
| Build do `web-client` lento/grande | ~2 GB de assets do jogo no contexto | normal; `.git` já é ignorado (`Dockerfile.dockerignore`) |
| `dotnet build` local falha em `npx rimraf` / `node.exe` | falta `-p:ci=true` | sempre `-p:ci=true` (também no `restore`) |
| Plugin custom não aparece no Admin | DLL não carregada | log deve ter `[MuCustom.StartupHook] loaded ...`; nome do assembly precisa começar com `MuCustom.` |
| Linux/VPS: `bad interpreter` / `\r` nos scripts | checkout com CRLF | o `.gitattributes` força LF; `git add --renormalize . && git checkout .` |
| Windows: popup repetido "Remote Desktop — Could not load the Remote Desktop Services ActiveX control (rdclientax.dll)" | o WSLg (GUI Linux do WSL, `C:\Program Files\WSL\msrdc.exe`) falha; o Docker não precisa dele | `%USERPROFILE%\.wslconfig` com `[wsl2]` + `guiApplications=false`, depois `wsl --shutdown` e reabrir o Docker Desktop |
| Login retorna `AccountAlreadyConnected` | a conta já está jogando (ex. aberta no navegador) | comportamento correto do OpenMU; o smoke test usa `test9` para não colidir |
| Página do jogo baixa como arquivo / navegador não exibe | `Content-Type: application/octet-stream` (bloco `types` do nginx no nível do server substitui o `mime.types`) | já corrigido em `services/web-client/nginx.conf` e `infra/nginx/docs.conf`; o smoke test confere o Content-Type |
| Git Bash: `docker ... -w /app` vira `C:/Program Files/Git/app` | conversão automática de caminhos do MSYS | os scripts desligam a conversão só para o docker (`scripts/lib.sh`); em comandos manuais use `MSYS_NO_PATHCONV=1` |
| Ferramenta/navegador não resolve `play.localhost` | alguns ambientes não resolvem subdomínios de `localhost` | `MU_ENV=dev` → `http://127.0.0.1/?ws=ws://127.0.0.1:80`, ou entradas no arquivo hosts |
| Web: no console, `game server 127.127.127.127:55902 closed the connection; retrying on openmu:55902` | o cliente tenta antes o IP anunciado (fora da allowlist do proxy) | esperado; a segunda tentativa conecta (B11 no STATUS) |

## Cliente web — protocolo estendido e patches

| Sintoma | Causa | Solução |
|---|---|---|
| Build do `web-client` falha com `patch não aplicou: 000N-…` | checkout de `clients/web` com finais de linha convertidos (Git no Windows, `core.autocrlf=true`) ou upstream mudou | `scripts/bootstrap-local.sh` (aplica `core.autocrlf=false` e refaz o checkout); se o upstream mudou, rebase do branch `mu-custom/extended-protocol` e regerar os patches (docs/development.md) |
| Página recarrega sem parar ao clicar em Entrar | versão do mundo ≠ versão carregada (bug do upstream, corrigido no patch 0004) | rebuild do `web-client`; `VITE_DEFAULT_VERSION=season6x` já inicia na versão certa |
| Após "Trocar de personagem", o herói não aparece no mapa | B13: o servidor não reenviava o próprio jogador (corrigido por patch, D19) | rebuild do `openmu` (`docker compose build openmu`); confira `aplicado: 0001-fix-player…` no log do build |
| Item largado/dropado não aparece no chão | antes do patch 0006, um drop de 14 ou 21 bytes era lido como `MoneyDropped075`/`MoneyDropped` | rebuild do `web-client` com os patches atuais |
| Personagens da tela de seleção sem hover / não selecionam logo após um build novo | modelos ainda baixando (cache do navegador zerado pelo build) | aguarde alguns segundos e passe o mouse de novo |
| `ws-login-probe`/`LoginProbe` retorna `AccountAlreadyConnected` | a conta está em jogo em outra aba | comportamento correto; use outra conta (o smoke usa `test9`) |