Dépannage

Voici les modes de défaillance que vous êtes le plus susceptible de rencontrer, et comment dépasser chacun.

Endpoint bloqué en Pending

Symptôme : un endpoint reste en Pending pendant plus de quelques secondes à la création. La console n'affiche aucune erreur ; la CLI affiche le même état.

Cause probable : le pod de compute ne peut pas être planifié. Les raisons les plus courantes sont la pression du cluster (aucun nœud n'a le CPU ou la mémoire demandés libres) ou un identifiant de pull d'image périmé. Les deux sont des problèmes côté opérateur.

Que faire :

1. Attendez 60 secondes. La pression transitoire se résorbe généralement une fois qu'un autre endpoint se suspend.
2. Si cela ne se résorbe pas, supprimez l'endpoint et recréez-le. Le plan de contrôle réessaiera la planification sur un nœud différent.
3. Si la recréation aboutit aussi en Pending, le cluster n'est pas content. Déposez un rapport sur le suivi GitHub avec l'id de l'endpoint et l'heure horloge.

FATAL: endpoint unavailable à la première connexion

Symptôme : psql renvoie FATAL: endpoint unavailable à la toute première connexion à un endpoint fraîchement créé, ou après une longue inactivité.

Cause probable : course au démarrage à froid. L'état de l'endpoint est Stopped, votre paquet l'a réveillé, mais Postgres rejoue encore le WAL jusqu'au HEAD de la branche lorsque votre client abandonne.

Que faire : réessayez la connexion. Le démarrage à froid s'achève typiquement en 300–500 ms, mais le tout premier réveil d'un projet fraîchement créé, ou après une inactivité de 24 h+, peut prendre 10–30 secondes pendant que le cache de pages du pageserver se réchauffe. La plupart des pilotes le tolèrent si vous autorisez au moins une nouvelle tentative ; psql brut ne réessaie pas par défaut.

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

Si l'endpoint est toujours indisponible après 30 secondes, le pod lui-même peut avoir échoué — vérifiez l'état dans la console et consultez les conseils Pending ci-dessus.

Connexion refusée / expirée depuis une nouvelle IP

Symptôme : un client qui se connectait bien auparavant est refusé ou expire après un déplacement vers un nouveau réseau, ou un hôte fraîchement provisionné ne peut pas atteindre le projet du tout.

Cause probable : le projet a une liste d'autorisation d'IP et l'adresse du nouveau client est en dehors de chaque CIDR listé. Les sources non listées sont rejetées au niveau du proxy, et le blocage couvre le chemin de réveil.

Que faire : ajoutez le CIDR du client (keon ip-allow add <cidr>) ou videz la liste, puis accordez ~30 secondes pour que le changement se propage au proxy.

keon connection-string renvoie branch_not_found

Symptôme :

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

…mais la branche existe dans la console.

Cause probable : le nom ne correspond pas à une branche dans le projet que vous avez ciblé — généralement une faute de frappe, ou le mauvais --project. La CLI résout une branche par id ou par nom, que vous le passiez comme argument positionnel ou via --branch, de sorte qu'un nom qui existe se résoudra dans les deux cas.

Que faire : confirmez le nom de la branche et le projet :

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

La connexion renvoie access_denied

Symptôme : l'OAuth Google ou GitHub s'achève, mais la console redirige vers une page d'erreur citant access_denied.

Cause probable : la connexion peut être verrouillée par une liste d'autorisation d'e-mails pendant que nous intégrons de nouveaux comptes. Si votre adresse n'a pas été activée, le rappel de connexion la rejette.

Que faire : contactez votre opérateur pour faire activer votre adresse. Une fois ajoutée à la liste d'autorisation, la connexion s'achève normalement à la prochaine tentative.

La session de la console expire en cours de session

Symptôme : la console fonctionne un moment, puis renvoie soudainement des 401 à chaque appel API jusqu'à ce que vous vous déconnectiez et reconnectiez.

Cause probable : le JWT signé par cp a expiré et sa fenêtre de renouvellement a expiré. La console émet un JWT à courte durée de vie (≈15 minutes) et, pendant que vous êtes actif, le renouvelle en arrière-plan contre /v1/auth/refresh. La fenêtre de renouvellement est fixée à 12 heures à compter de la connexion : une session active se renouvelle indéfiniment, mais un onglet laissé intact au-delà de cette fenêtre ne peut plus se renouveler.

Que faire : déconnectez-vous et reconnectez-vous. Pour l'automatisation headless ou de longue durée, utilisez une clé API nsk_ plutôt qu'une session de navigateur — les clés API n'expirent pas et sont révoquées explicitement. Voir Authentification.

Où déposer des bugs

Pour tout ce qui n'est pas couvert ici :

• Bugs produit et demandes de fonctionnalités : le suivi GitHub.
• Vulnérabilités de sécurité : Sécurité — jamais sur le suivi public.

Des étapes de reproduction concrètes, les ids affectés (projet, branche, endpoint), et un horodatage horloge raccourcissent l'aller-retour de façon spectaculaire.