Solução de problemas

A Kisenon está em alpha. Aqui estão os modos de falha que você tem mais chance de encontrar, e como superar cada um.

Endpoint preso em Pending

Sintoma: um endpoint fica em Pending por mais que alguns segundos na criação. O console não mostra erro; a CLI mostra o mesmo estado.

Causa provável: o pod de compute não pode ser agendado. As razões mais comuns são pressão de cluster (nenhum node tem a CPU ou memória solicitada livre) ou uma credencial de image-pull desatualizada. Ambos são problemas do lado do operador.

O que fazer:

1. Aguarde 60 segundos. Pressão transitória geralmente passa quando outro endpoint suspende.
2. Se não passar, exclua o endpoint e recrie. O control plane tentará agendar em um node diferente.
3. Se a recriação também ficar em Pending, o cluster está infeliz. Abra um relatório no tracker do GitHub com o id do endpoint e o horário de relógio.

FATAL: endpoint unavailable na primeira conexão

Sintoma: psql retorna FATAL: endpoint unavailable na primeiríssima conexão a um endpoint recém-criado, ou após uma longa ociosidade.

Causa provável: corrida de cold-start. O estado do endpoint é Stopped, seu pacote o despertou, mas o Postgres ainda está reproduzindo o WAL até o HEAD do branch quando o seu cliente desiste.

O que fazer: tente a conexão novamente. O cold-start tipicamente completa em 300–500 ms, mas o primeiríssimo despertar de um projeto recém-criado, ou após uma ociosidade de 24h+, pode levar 10–30 segundos enquanto o cache de páginas do pageserver aquece. A maioria dos drivers tolera isso se você permitir ao menos uma nova tentativa; o psql puro não tenta novamente por padrão.

# psql with one explicit retry
for i in 1 2; do psql "$URI" -c '\q' && break; sleep 5; done

Se o endpoint ainda estiver indisponível após 30 segundos, o próprio pod pode ter falhado — verifique o estado no console e consulte a orientação de Pending acima.

keon connection-string retorna branch_not_found

Sintoma:

$ keon connection-string my-feature --project prj_abc...
Error: branch_not_found: my-feature

…mas o branch existe no console.

Causa provável: o nome não corresponde a um branch no projeto que você mirou — geralmente um erro de digitação, ou o --project errado. A CLI resolve um branch por id ou por nome, quer você o passe como o argumento posicional ou via --branch, então um nome que de fato existe resolverá de qualquer forma.

O que fazer: confirme o nome do branch e o projeto:

keon branches list --project prj_abc...
keon connection-string my-feature --project prj_abc...

Sign-in retorna access_denied

Sintoma: o OAuth do Google ou GitHub completa, mas o console redireciona para uma página de erro citando access_denied.

Causa provável: durante o alpha, o sign-in é restrito por uma allowlist de e-mail. Se o seu endereço não foi cadastrado, o callback de sign-in o rejeita por princípio.

O que fazer: candidate-se em Acesso ao alpha. Uma vez que o seu endereço seja adicionado à allowlist, o sign-in completa normalmente na próxima tentativa.

Sessão do console expira no meio da sessão

Sintoma: o console funciona por um tempo, depois subitamente retorna 401s em toda chamada de API até você fazer sign-out e sign-in novamente.

Causa provável: o JWT assinado pelo cp expirou e a sua janela de renovação expirou. O console cunha um JWT de vida curta (≈15 minutos) e, enquanto você está ativo, o renova em segundo plano contra /v1/auth/refresh. A janela de renovação é fixa em 12 horas a partir do sign-in: uma sessão ativa se renova indefinidamente, mas uma aba deixada intocada além dessa janela não consegue mais renovar.

O que fazer: faça sign-out e sign-in novamente. Para automação headless ou de longa duração, use uma chave de API nsk_ em vez de uma sessão de navegador — chaves de API não expiram e são revogadas explicitamente. Veja Autenticação.

Onde abrir bugs

Para qualquer coisa não coberta aqui:

• Bugs de produto e solicitações de funcionalidades: o tracker do GitHub.
• Vulnerabilidades de segurança: Segurança — nunca no tracker público.

Passos de repro concretos, os ids afetados (projeto, branch, endpoint), e um timestamp de relógio encurtam o ciclo dramaticamente.