Para investigar uma falha, comece pelo doctor. Ele confere o runtime e o
estado da instalação (incluindo os restos do SetupVibe 1) e mostra um comando
de correção ao lado de cada achado. Este capítulo explica os sintomas
identificados por essas verificações e os termos usados no guia.
Comece pelo doctor
setupvibe doctorUm ✗ é problema e um ! é aviso. Cada linha que exige ação traz o comando
que resolve. Quando o achado é de nível fail, o comando termina com 3,
CONFIG. Leia a mensagem para identificar a falha apontada pela verificação.
Sintomas e saídas
| Sintoma | Causa provável | Comando |
|---|---|---|
sudo asks for a password |
o passo privilegiado usa sudo -n e não há senha em cache |
setupvibe user nopasswd <user> ou sudo -v antes |
Another SetupVibe run is in progress |
outra execução segura run.lock |
cat ~/.setupvibe/run.lock e esperar |
| erro de TLS ou certificado em download | proxy ou CA corporativa | --ca-file e HTTPS_PROXY, se necessário |
github.com unreachable |
rede ou DNS | setupvibe system e --cache-dir |
| relógio mais de cinco minutos fora | NTP desligado | sudo timedatectl set-ntp true |
3.2 GB free, 10 GB needed |
pouco espaço na pasta pessoal | liberar espaço ou mover o cache |
item com status other |
outra cópia instalada por APT, Homebrew ou npm | setupvibe install <item> e conferir o PATH |
3 of 42 steps failed |
falha parcial; o resto ficou aplicado | ler o log e repetir só o que faltou |
SetupVibe 1 found |
máquina preparada pela versão 1 | setupvibe migrate --dry-run |
! Restart needed |
/var/run/reboot-required existe |
reiniciar ou auto --reboot |
container publicando em 0.0.0.0 |
Docker não passa pelo UFW | publicar em 127.0.0.1 |
| alias não definido | já existe comando com o mesmo nome | conferir com type <nome> |
settings.json inválido |
valor fora do schema | setupvibe config list e corrigir |
Run: setupvibe upgrade |
arquivo de estado de versão mais nova | setupvibe upgrade |
| comando em pipe imprime a ajuda e sai com 2 | sem TTY | rodar no terminal ou usar o CLI |
| duas edições na mesma máquina | desktop e server são exclusivas | setupvibe self uninstall antes da troca |
Sudo sem senha
O auto exige sudo sem senha porque não abre prompt. init, migrate e
shell apply pedem a senha uma vez num terminal e seguem com a credencial em
cache. Sem terminal, os comandos param antes de alterar a máquina.
setupvibe user nopasswd deploysudo -v && setupvibe auto --user deployO exit code é 13, SUDO_PASSWORD. Com --keep-nopasswd, o auto mantém a
regra temporária que ele criou.
Falha parcial
Um passo com falha não interrompe os seguintes. O resultado fica no log e no
last-run.json com status por item. O comando termina com 10, PARTIAL.
Corrija a causa e repita só o que faltou:
setupvibe doctorsetupvibe install node python --forcesetupvibe checkNão é preciso recomeçar do zero: o que passou continua aplicado.
Ferramenta de outro gerenciador
other aparece quando o comando existe fora das pastas do mise e de
~/.local/bin. O SetupVibe preserva a cópia existente e instala a
dele ao lado. Para conferir qual responde primeiro:
setupvibe list --checkcommand -v nodesetupvibe install nodeSe a versão ativa continuar sendo a outra, ajuste o PATH ou remova a cópia
antiga. O doctor mostra o caminho da cópia que ganhou a disputa.
Onde ler mais
setupvibe --skill troubleshootingimprime a mesma matéria com o detalhe de cada caso, dentro do binário.- O apêndice de códigos de saída, no fim do livro, lista a classe de cada número.
- O apêndice de configuração explica cada arquivo de
~/.setupvibe/. setupvibe reportgera o Markdown para anexar numa issue e encaminhar a investigação ao suporte.
Glossário
| Termo | Significado |
|---|---|
| item | uma ferramenta da lista embutida, com id, versão, método e verificação |
| seleção | o conjunto de itens escolhidos, gravado em selection.json |
| perfil | um recorte nomeado da lista, como essencial e remoto |
| versão fixada | a versão que o binário instala e confere, não a última do fornecedor |
| adotado | item que já estava na máquina e foi registrado pelo init sem ser instalado |
| outro gerenciador | cópia instalada por APT, Homebrew, npm ou instalador do fornecedor |
| bloco do shell | trecho entre # >>> setupvibe >>> e # <<< setupvibe <<< |
| run log | arquivo em ~/.setupvibe/logs/, com um evento NDJSON por linha |
| cofre | credentials.json, cifrado com AES-256-GCM |
| master key | chave de 32 bytes que abre o cofre; fica em master.key ou em variável |
| variante | classificação da máquina: local, remota sem interface ou remota exposta |
| headless | máquina sem sessão gráfica; itens gui ficam de fora |
| dry run | execução que mostra o plano e não altera nada |
| canal | stable ou beta, de onde o upgrade e o aviso de versão leem |
| exit code | número que classifica o resultado do comando, de 0 a 130 |
| OpenCLI | descrição JSON da árvore de commands, impressa por --opencli |
| envelope | objeto { ok, command, data } ou { ok, command, error } do --json |
Fechamento
O guia termina nos apêndices. Quando precisar da lista exata de uma option, do conteúdo de um arquivo de estado ou do significado de um exit code, comece por eles. Para consultar a origem de uma alteração na máquina, volte ao capítulo da operação correspondente.