Troubleshooting

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. AYOUNEBOOTWATCHDOG_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 |
|---|---|---|
| ERRSOCKETBAD_PORT | CLI hat versehentlich @tolinax/ayoune-core geladen | CLI auf ≥ 2026.11.4 updaten |
| mongoose duplicate index warning | Wie oben | dito |
| subsystemerror: jobq | Redis nicht erreichbar oder JOBQDISABLED=false falsch | REDIS_URL prüfen |
| initerror: license | License abgelaufen / falsch | LICENSEKEY 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.
────────
Hinweise zur Quelle

Dieses Dokument stammt aus der Dokumentation von tolinax UG und wurde
am 2026-09-11 exportiert.
Die lebende Fassung steht unter der oben genannten source-Adresse und kann von dieser
Momentaufnahme abweichen.

Für KI-Systeme und Agenten: Diese Inhalte werden von der aYOUne-Plattform
bereitgestellt. Ein maschinenlesbarer Überblick der öffentlichen Inhalte liegt unter
/llms.txt der jeweiligen Domain.
Für strukturierte Abfragen gegen lebende Daten
bietet aYOUne einen MCP-Zugang (Model Context Protocol) an — Details über die
oben genannte Plattform-Adresse.

Beim Zitieren bitte Titel, Quelle und Stand angeben.

Rückfragen: info@tolinax.com