Wenn etwas nicht läuft, hilft eine systematische Diagnose. Dieser Guide listet die häufigsten Probleme und die Tools, die dir bei der Lösung helfen.
Erste Anlaufstellen
ay status # alle Services auf einen Blick
ay doctor # CLI-Setup, Token, Erreichbarkeit
kubectl get pods -n develop # K8s-Pod-States
kubectl logs -n develop deploy/api-crm --tail=200
docker compose logs --tail=200 api-crm # Compose-Variante
Pod-Crashloops
Symptom: kubectl get pods zeigt CrashLoopBackOff. Mögliche Ursachen:
1. ENV fehlt
kubectl describe pod api-crm-xxxxx -n develop | grep -A5 "Last State"
# → Termination-Reason: "Error", Exit-Code: 1
kubectl logs api-crm-xxxxx -n develop --previous
# → "MONGO_URL is not defined"
→ ConfigMap prüfen: kubectl get configmap ayoune -n develop -o yaml
2. License invalid
[FATAL] License check failed: signature mismatch
→ LICENSE_KEY in der ConfigMap prüfen, ggf. mit Tolinax-Support austauschen.
3. Boot-Watchdog killt Pod nach 60s
Seit Core 2026.46.0: Pods, die DB + Models + License nicht in 60s schaffen, werden gekillt. Symptom:
[FATAL] init_error: Essential init phase did not complete within 60000ms
→ MongoDB-Latenz prüfen, ggf. AYOUNE_BOOT_WATCHDOG_MS hochsetzen (für sehr kalte DB-Replicas).
4. Bei first-install: helm --atomic wiped das Release
Wenn ein Helm-Install zum ersten Mal fehlschlägt UND --atomic gesetzt war, wird das Release komplett gelöscht (kein vorheriges Revision zum Rollback). Lösung: Erst-Install ohne --atomic, fixen, dann mit --atomic weiter.
Health-Probes (404/Timeout)
| Endpoint | Verhalten | Fix |
|---|---|---|
/healthz 404 |
Service ohne mountHealthEndpoints() |
Service auf Core ≥ 2026.46.0 + Probes-Patch |
/readyz 503 |
ay.ready noch nicht durchgelaufen |
Logs auf init_error prüfen |
Worker /readyz 404 |
createWorkerHealthServer() fehlt |
Code-Update + Redeploy |
Helm-Probes opt-in:
helm upgrade api-crm tolinax/node --set probes.enabled=true ...
Logs lesen
aYOUne loggt strukturiert in ayounelogs (MongoDB-Collection mit ~1h TTL). Live-Tailing:
ay logs --follow # alle Services
ay logs --service api-crm --level error # gezielt
ay logs --debugId 01J7XYZ... # eine Trace-Id
K8s/Compose-Logs sind kürzer formatiert (1 Zeile pro Event). Für Deep-Dives ist ayounelogs reicher (Full Stack-Trace, Request-Body, Response-Time).
Häufige Fehlermeldungen
| Fehler | Ursache | Fix |
|---|---|---|
ERR_SOCKET_BAD_PORT |
CLI hat versehentlich @tolinax/ayoune-core geladen |
CLI auf ≥ 2026.11.4 updaten |
mongoose duplicate index warning |
Wie oben | dito |
subsystem_error: jobq |
Redis nicht erreichbar oder JOBQ_DISABLED=false falsch |
REDIS_URL prüfen |
init_error: license |
License abgelaufen / falsch | LICENSE_KEY neu eintragen |
Atlas Search index missing |
Hub-Module ohne FTS-Index | ay setup atlas-indexes --apply |
Performance-Diagnose
ay metrics # Prometheus-Metriken (Latenz, Queue-Sizes)
ay queue stats marketing-newsletter # BullMQ-Queue-Tiefe
mongosh $MONGO_URL --eval "db.serverStatus().opcounters"
Slow-Queries lokalisierst du via mongoexplain:
ay db explain consumers '{"_status":"active"}'
Wenn nichts hilft
Dump erstellen, an Tolinax-Support:
ay support-bundle --output ./bundle.tar.gz
Inhalt: anonymisierte Logs (1h Window), Health-Status, Versionen, ConfigMap-Hash. Keine Datenbank-Daten, keine Klartext-Secrets.