| Sintoma | Verificação / ação |
|---|---|
node/npm ausente | Reabra terminal, carregue nvm ou ajuste PATH. |
| Node abaixo de 20 | Atualize antes de instalar/compilar. |
npm start falha no Windows | Use WSL2; ajuda nativa via node bin/cockpit.js --help. |
build ausente | npm run build ou npm run build:all. |
SPA não compilada | npm --prefix web ci e npm run build:web, ou --headless para API. |
| Dependências web ausentes | Instalar na raiz não basta; npm --prefix web ci. |
| Erro de lockfile | Confira se manifest/lockfile são da mesma revisão; não apague lockfiles como primeiro recurso. |
EADDRINUSE | Use --port 4100 ou encerre a instância da porta. |
Agente ausente / ENOENT | command -v <runner> no ambiente do servidor; reinicie após instalar. |
| Agente instalado não funciona | Confirme autenticação, modelo e acesso diretamente no CLI. |
| Sem TTY/resize | Confira ptyBackend, python3 e imports POSIX; pipe é limitado. |
HEAD inválido | Commit inicial e git rev-parse HEAD. |
| Pasta sem permissão | Use pasta gravável e confira proprietário; não rode servidor como root. |
dubious ownership | Confira dono do repositório e ajuste apenas o alvo verificado. |
.env/worktree recusado | Confira configuração, contenção e allowEnvCopy. |
401 | Token/convite inválido, dispositivo expirado ou revogado. |
403 read_only | Escopo monitor; use convite com a permissão necessária. |
403 local_only | Gestão de convites via localhost do servidor. |
403 origin_denied | Confira endereço, porta e origem preservada pelo proxy. |
| Sem acesso na rede | Confira bind, IP, firewall, porta e conectividade WSL. |
| Sem microfone | Autorize captura; use localhost ou HTTPS remoto. |
| Transcrição lenta/falha | Confira download do modelo, memória, modelo e formato do áudio. |
| Mídia não instala | Confira internet, prefixo global npm e permissões; autentique depois. |
| Ombro sem síntese | Confira endpoint Ollama, serviço, tag/modelo e habilitação. |
| DSH indisponível | Confira entrypoint, diretório isolado existente e diferença de ~/.dsh. |
| Testes sem navegador | Instale Chromium do Playwright e bibliotecas necessárias no Linux. |
Para investigar, use --log-level debug e /api/health. Remova segredos de logs antes de compartilhá-los.