08 — Dépannage¶

Durée : référence · Persona : tout le monde · Voie : A ou B

Un catalogue pragmatique des problèmes les plus probables pendant votre onboarding, avec le fix éprouvé.

Pré-requis

Au moins une plateforme sous la main (https://demo.akko-ai.com ou votre https://demo.akko.local local).

Health check rapide¶

Lancez ça en premier dès que quelque chose semble étrange :

# Démo live
curl -sk https://demo.akko-ai.com/api/health/all | jq

# k3d local
curl -sk https://demo.akko.local/api/health/all | jq

Attendu : chaque couche renvoie { "status": "ok" }.

Si une couche est dégradée, le reste de cette page vous dit quel bouton tourner.

1. « Service shows down » dans le cockpit¶

Cause	Fix
Sous-chart encore en rolling	`kubectl get pods -n akko` et attendre `Running`.
Sous-chart en crash loop	`kubectl logs -n akko <pod>` → chercher la cause du `CrashLoopBackOff`.
Network policy qui bloque la sonde de santé	`kubectl describe pod -n akko <pod>` → « egress denied ». Mettre à jour la NP.
Endpoint santé déplacé dans une nouvelle release	`kubectl describe svc -n akko <svc>` puis mettre à jour la table de routes santé du cockpit.
Dépendance externe tombée	Si votre source catalogue est offline, la santé de la source passe rouge, pas la couche AKKO.

Premier réflexe. Regarder la page Logs du cockpit filtrée sur le service défaillant avant de plonger dans kubectl.

2. Boucle de redirection SSO¶

Vous vous connectez, vous reboucler sur l'écran de login, vous vous reconnectez, vous reboucler…

Cause	Fix
Cookies tiers bloqués	Autoriser les cookies pour `*.akko-ai.com` (ou votre domaine local).
Safari ITP cookie partitioning	Ouvrir le cockpit dans une fenêtre non-privée ; vérifier que « Prevent cross-site tracking » ne supprime pas le cookie SSO.
Décalage horaire entre le navigateur et le fournisseur d'identité	Synchroniser l'horloge du laptop.
Cookies résiduels d'un déploiement précédent	Vider les cookies du domaine AKKO, se reconnecter.
Mauvais redirect-uri du client fournisseur d'identité	Lancer `bash helm/scripts/keycloak-rest-patch-redirect-uris.sh` (local) ou attendre le hook de sync redirect-uri (live).

3. Le résultat ADEN est vide¶

Cause	Fix
Catalogue tout juste réinjecté	Attendre 30 sec, recliquer Generate.
Le scope exclut vos tables	Basculer le chip scope sur un que votre persona possède.
Le filtre de ligne a masqué toutes les lignes	Essayer une question moins restrictive (ex. lâcher le filtre `region`).
Score de match semantic layer très bas	Reformuler la question avec des noms de tables explicites.
Warmup du moteur	Second run < 3 sec — retenter.

4. Les tests Playwright skipent¶

Vous avez lancé pytest tests/e2e/playwright/ et la plupart des tests reportent SKIPPED.

Cause	Fix
Drift du FQDN fournisseur d'identité (ex. `auth.<domain>` au lieu d'`identity.<domain>`)	La suite auto-résout `identity` / `keycloak` / `auth`. Si les trois échouent, vérifier le routage frontal.
Cluster pas joignable	`curl -sk https://demo.akko-ai.com/` doit répondre 302. Si 000, vérifier DNS / VPN.
Persona pas injecté	`bash helm/scripts/seed-keycloak-personas.sh`.
Mauvais env de domaine	`AKKO_DOMAIN=demo.akko-ai.com pytest …`.
Démarrage à froid, fournisseur d'identité qui renvoie 504	Attendre 30 sec puis relancer.

Le skip-cleanly est par design : la suite refuse d'asserter vert sur une plateforme à moitié up. Lire la raison du skip dans la sortie pytest.

5. Helm upgrade échoué¶

Cause	Fix
Vous avez utilisé `--reset-values`	JAMAIS `--reset-values`. Toujours `--reuse-values -f helm/examples/values-netcup.yaml`.
Image sous-chart cachée comme `docker.io/library/akko-X:tag`	Cache shadow containerd. Re-tagger avec le préfixe registry local.
Fichier realm pas passé via `--set-file`	Ajouter `--set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json`.
Half-migration : `_required("AKKO_FOO")` dans le code sans l'`env: name: AKKO_FOO` helm correspondant	Mettre à jour code et helm dans la même PR.
Pod qui attend un Secret que le chart n'a pas créé	Vérifier `kubectl describe pod` pour `FailedMount`.

Règle d'or. Un helm upgrade ne devrait jamais nécessiter une mutation CLI. Si vous avez touché à kubectl set image, capturer le gap comme fix de chart et relancer l'upgrade.

6. Le cockpit affiche le build précédent¶

Cause	Fix
Tag d'image réutilisé (ex. `akko-cockpit:2026.05`)	Lancer `bash scripts/deploy-cockpit.sh` — il timestampe le tag.
Cache navigateur	Hard refresh (`Cmd-Shift-R`).
Service worker qui retient l'ancien bundle	DevTools → Application → Service Workers → Unregister, refresh.
Rollout du pod pendant	`kubectl rollout status deploy/akko-cockpit -n akko`.

7. k3d local : les pods restent `Pending`¶

Cause	Fix
Plus de mémoire sur Docker Desktop	Monter à 16 Go dans les préférences Docker Desktop.
Plus de disque	`docker system prune -f`.
`imagePullBackOff` sur une image custom	Lancer `bash helm/scripts/build-images.sh` pour pousser sur le registry local k3d.
PVC non bound	Provisionner local-path k3d manquant ; relancer `bash helm/scripts/k3d-create.sh`.

Liens vers les runbooks détaillés¶

En cas de doute¶

Regardez la page Alerts du cockpit — elle remonte les alertes actionnables avant que quiconque ne demande.
Ouvrez DEMO_HOST/docs/admin/troubleshooting/ pour le handbook de dépannage complet.
Ouvrez une issue sur github.com/AKKO-p/AKKO avec la sortie du curl health attachée.

Suivant : 09 — Prochaines étapes.