Solução de problemas
A maioria dos problemas no dia a dia cai em alguns padrões: a sessão expirou, um modelo precisa de login, uma skill não tem o segredo de que precisa, ou uma superfície perdeu a conexão com o Engine. Use a tabela abaixo para ir direto à causa e à solução; depois, se precisar, colete um diagnóstico.
Sintoma → causa → solução
| Sintoma | Causa provável | Solução |
|---|---|---|
| "Sessão expirada" ou erro 401 | O token de identidade expirou ou foi revogado | Refaça o login: /login (TUI/VS Code) ou Sign in (Desktop). |
| "PolicyContext não configurado — refaça o login" | A sessão começou sem a política da org carregada | Entre novamente para recarregar a política. |
| "cloud API key is required for model nnumbers" (VS Code) | O token de login não chegou ao Engine | Faça login pela extensão (Imaginne: Login ou /login). |
Skill pede um segredo ausente (missing_required_env) | A org não configurou/anexou o env-secret que a skill declara | Peça ao admin para criar e anexar o env-secret. Veja Env-secrets de skills. |
| Skill não aparece ou é recusada | Você não tem um perfil que inclua aquela skill | Peça ao admin para atribuí-la ao seu perfil. Veja Perfis. |
| Voz indisponível | Sem microfone/permissão, sem credencial da org, ou build sem a tag voice | Confira permissão do sistema, habilitação pela org e, na TUI, o build. Veja Voz. |
| "Engine disconnected" (VS Code) | A extensão não conseguiu subir/alcançar o CLI imaginne | Rode Imaginne: Run Health Check; se preciso, configure imaginne.binaryPath. |
| "requires a TTY-capable terminal" (TUI) | A TUI foi iniciada sem um terminal interativo | Abra-a em um terminal de verdade (não em um pipe ou tarefa sem TTY). |
| Modelo bloqueado / lista de modelos vazia | A política da org restringe os modelos disponíveis | Use nnumbers (padrão) ou peça ao admin. Veja Modelos. |
| "Muitas execuções simultâneas" (chat web) | Você tem 10 execuções ativas ao mesmo tempo | Aguarde uma terminar ou interrompa alguma pelo botão parar. Veja Chat no navegador. |
| "Tipo não suportado" / "Arquivo maior que o limite" (chat web) | O anexo está fora da lista de tipos aceitos ou passa de 50 MB | Converta o arquivo ou divida-o. Veja Anexos & arquivos. |
| "Um anexo falhou — remova-o e envie novamente" (chat web) | O upload de um anexo não terminou | Remova o chip com erro e reenvie a mensagem. |
| "Seu espaço está cheio" (chat web) | Os 100 MB de arquivos da conta acabaram | Exclua arquivos no painel Arquivos. Veja Anexos & arquivos. |
| Arquivo antigo aparece como "indisponível" (chat web) | O conteúdo não está mais guardado | Peça ao agente para gerar o arquivo de novo. |
| "Seu espaço de memória está cheio" (chat web) | Os 256 KB de memória da conta acabaram | Remova memórias que não valem mais. Veja Memória da conta. |
Modelo precisa de login
Mensagens do tipo "cloud API key is required for model nnumbers" (no VS Code) ou falhas de autenticação ao chamar o modelo quase sempre significam que o login não chegou ao Engine — não que você precise de uma chave de API. O Imaginne usa a sua sessão autenticada (o seu login na organização); você não gerencia chaves. Refaça o login pela superfície que está usando. Veja Identidade.
Skill sem env ou recusada
Duas situações distintas:
missing_required_env— a skill declara um segredo (viarequired_env) que a sua organização ainda não configurou. Só um admin resolve, criando o env-secret e anexando-o à skill. Veja Env-secrets (admin).- Skill some da lista ou é recusada — você não tem um perfil que conceda acesso àquela skill. Peça ao admin para incluí-la no seu perfil. Sem nenhum perfil, o chat fica vazio. Veja Perfis.
Voz indisponível
Se o botão de microfone (Desktop e chat web) ou os atalhos Ctrl+G / F2 (TUI) não funcionam, verifique nesta ordem:
- Permissão de microfone — do sistema operacional (Desktop/TUI) ou do navegador (chat web).
- Credenciais de voz habilitadas pela sua organização.
- Na TUI, um build com a tag
voice(hoje, só o release darwin-arm64). - No chat web, um navegador com suporte a gravação de áudio — sem ele, o botão de microfone nem aparece.
Detalhes em Voz.
Coletar um diagnóstico
Quando o problema persistir, gere um diagnóstico para você mesmo ou para enviar ao suporte da sua organização.
- Desktop
- Terminal (TUI)
- VS Code
- Export Support Bundle — gera um pacote de diagnóstico redigido (sem tokens nem segredos). Use-o para anexar ao suporte.
/fb <mensagem>— envia feedback diretamente do app, com contexto da sessão.
/diagnostics— mostra o estado de configuração e conexão./feedback(ou/fb) — envia feedback com contexto./statuse/whoamiajudam a confirmar conexão e identidade.
- Imaginne: Run Health Check — verifica se o Engine está acessível e aponta o que corrigir.
- Imaginne: Whoami — confirma a sua identidade ativa.
O Support Bundle do Desktop e o feedback (/fb) não incluem o seu token nem segredos. Veja Credenciais para entender o que nunca sai da sua máquina.
Veja também
Esta página ajudou?
Reportar um problema nesta páginaNão envie senhas, chaves, tokens ou dados de clientes.