Solução de problemas

O que fazer quando algo não funciona: inicialização, indexação, IA, Claude Code, Git, banco de dados e build.

Antes de tudo, duas ferramentas que sempre ajudam:

Ajuda → Registro de erros… mostra os erros recentes do IDE.
Ajuda → Relatar um problema… monta um .zip com o necessário para o diagnóstico, sem o seu código nem as suas conversas. Copiar resumo fornece o texto pronto para colar.

Pergunte ao agente: “o que está falhando?”. Com yuli_health, ele revisa problemas, execução, testes, terminais e registros do Yuli de uma só vez.

Instalação e inicialização

Sintoma	O que fazer
O Windows exibe um alerta ao executar o instalador	Confirme que você baixou da fonte oficial e que o editor do certificado é “Yuli Code”.
O AppImage não abre no Linux	Dê permissão de execução com `chmod +x`.
A versão portátil demora na primeira vez	É normal: ela descompacta o aplicativo uma vez por versão. Depois, inicia na hora.
A interface está em outro idioma	Opções globais → Aparência → Idioma. Veja Idiomas.
Você quer medir por que a inicialização demora	Ajuda → Desempenho de inicialização….

Sintoma	O que fazer
Faltam referências ou a navegação está incompleta	Aguarde o fim da indexação (barra superior do editor).
O Lombok ou as dependências não são resolvidos	O projeto pode estar em modo restrito. Opções globais → Segurança → Projetos confiáveis → Confiar.
Aviso “Sem servidor de linguagem para…”	Clique em Instalar… e autorize o download.
O índice parece desatualizado	Ferramentas → Limpar cache… apaga índices e estado salvo; o Yuli os regenera.
Falta um JDK, Maven ou Gradle	O Yuli oferece o download. Configure-o em Projeto → Build, execução e depuração….

Sintoma	O que fazer
Erro de autenticação no Modo Platform	Revise a API key na configuração do modelo e clique em Testar conexão.
Um modelo local não responde	Confirme que o servidor está rodando e que a URL do servidor está correta.
O provedor está fora do ar	O Yuli respeita o `retry-after` do provedor. Aguarde ou troque de provedor.
Uma tarefa em segundo plano parou	Ela atingiu o teto de tokens ou de custo: Ampliar limite e retomar.
A equipe de agentes foi pausada	Ela atingiu o orçamento. Amplie-o em Mais ações → Equipe de agentes.

Sintoma	O que fazer
O Yuli não encontra o agente	Instale-o com o instalador oficial e clique em Detectar novamente.
“Aguardando o Claude Code usar as ferramentas do Yuli”	Aprove o servidor `yuli` ou clique em Aprovar agora. Confira com `/mcp`.
`/mcp` mostra `yuli` com erro	Abra o projeto no Yuli: as ferramentas só funcionam com o Yuli aberto. `yuli_status` explica o motivo.
As regras não mudaram	Elas são carregadas ao iniciar a sessão: reinicie-a pela barra do agente.
O Codex diz que falta o adaptador	Instale o `codex-acp`: `npm install -g @openai/codex @agentclientprotocol/codex-acp`.
O Kiro pede atualização	O Yuli precisa do Kiro CLI 1.28.2 ou posterior.
Não quero que o Yuli bloqueie nada	Desative Fazer cumprir as regras (“Só avisar”). Git e segredos são sempre protegidos.

Sintoma	Por quê	O que fazer
Não faz commit nem push	O Git só é habilitado com um pedido explícito.	Peça: “faça commit e push”. Aprove cada ação.
Não cria um branch	Branches exigem um pedido próprio.	Peça o branch explicitamente.
Não lê um arquivo	É um arquivo de segredos (`.env`, chaves, credenciais).	É intencional. Passe a informação sem o segredo.
Não consegue escrever fora do projeto	O sandbox o limita ao projeto.	Projeto → Acesso a pastas…
Não executa uma instrução no banco	A conexão não tem Superpermissões para essa classe.	Ajuste o Acesso do agente da conexão.
Não avança para Testes	A medição está pendente ou pediu para iterar.	Veja a aba Medição do painel Qualidade.
Não termina o turno	Falta a verificação verde.	Veja o que está falhando em Execução, Testes ou Problemas.

Sintoma	O que fazer
Uma operação demora demais	Quando o limite expira, aparece Tentar novamente.
Erro de certificado com um servidor interno	Marque a confiança no certificado; o Yuli lembra a decisão por servidor.
Não consigo fazer commit por causa do gate	Leia o controle que falhou (segredos, integridade dos testes, tamanho, caminhos protegidos). Corrija ou peça uma exceção com vencimento.
Os hooks do Yuli não foram instalados	Já existe outra ferramenta em `core.hooksPath` (por exemplo, husky). O Yuli não a substitui.

Sintoma	O que fazer
“Para conectar ao Oracle é necessário o Oracle Instant Client”	Instale o Instant Client 19c ou posterior e adicione-o ao `PATH`.
Erro de certificado	Marque Confiar no certificado do servidor na conexão.
O agente não vê uma conexão	O acesso dela está em Sem acesso.
Uma consulta do agente foi interrompida	Ela passou de 45 segundos ou o plano dela estima uma varredura grande demais. Restrinja a consulta.

Sintoma	O que fazer
“O Docker não está disponível”	Inicie o Docker e clique em Tentar novamente.
“O kubectl não está configurado”	Instale o `kubectl` e configure um contexto (kubeconfig).