aYOUne

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. 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.

Mit dieser Seite weiterarbeiten

Fertige Anweisungen für dein KI-Werkzeug. Kopieren, einfügen, loslegen — die KI holt sich den Inhalt selbst über die Adresse im Text.

Die Schritte für mich zusammenfassen Das Wesentliche, in der richtigen Reihenfolge.
In ChatGPT öffnen 
Lies die folgende Dokumentation von tolinax UG und arbeite damit.

Diese Seite: https://ayoune.com/de/docs/self-hosting/troubleshooting.md
Die vollständige Sammlung: https://ayoune.com/de/docs/self-hosting.md

Fasse den Inhalt für mich zusammen.

- Zuerst in zwei Sätzen: worum geht es hier?
- Dann die Schritte in der Reihenfolge, in der ich sie gehen muss.
- Je Schritt eine Zeile, in einfacher Sprache.
- Am Ende: was ich vorher bereithalten sollte.

Lass nichts weg, was ich brauche, um wirklich fertig zu werden.
Hinweis zu den Quellen:
- Jede Seite dieser Dokumentation ist als Markdown abrufbar (dieselbe Adresse mit `.md`).
- Ein maschinenlesbarer Überblick aller öffentlichen Inhalte liegt unter `/llms.txt`.
- Falls du Zugriff auf den aYOUne-MCP-Server hast, kannst du damit gegen lebende Daten
  arbeiten statt gegen diese Momentaufnahme. Falls nicht, ignoriere diesen Punkt.
Bei der Einrichtung helfen Schritt für Schritt, mit Rückfragen an mich.
In ChatGPT öffnen 
Lies die folgende Dokumentation von tolinax UG und arbeite damit.

Diese Seite: https://ayoune.com/de/docs/self-hosting/troubleshooting.md
Die vollständige Sammlung: https://ayoune.com/de/docs/self-hosting.md

Begleite mich Schritt für Schritt durch die Einrichtung.

- Sag mir zuerst, was ich bereithalten muss (Zugänge, Daten, Zeit).
- Dann führe mich EINEN Schritt nach dem anderen. Warte auf mein "weiter".
- Nenne je Schritt, woran ich merke, dass er geklappt hat.
- Wenn etwas schiefgeht, frag nach der genauen Meldung, statt zu raten.

Wenn die Anleitung eine Stelle offen lässt, sag mir das, statt sie zu erfinden.
Hinweis zu den Quellen:
- Jede Seite dieser Dokumentation ist als Markdown abrufbar (dieselbe Adresse mit `.md`).
- Ein maschinenlesbarer Überblick aller öffentlichen Inhalte liegt unter `/llms.txt`.
- Falls du Zugriff auf den aYOUne-MCP-Server hast, kannst du damit gegen lebende Daten
  arbeiten statt gegen diese Momentaufnahme. Falls nicht, ignoriere diesen Punkt.
Bei einem Problem weiterhelfen Ursache eingrenzen statt raten.
In ChatGPT öffnen 
Lies die folgende Dokumentation von tolinax UG und arbeite damit.

Diese Seite: https://ayoune.com/de/docs/self-hosting/troubleshooting.md
Die vollständige Sammlung: https://ayoune.com/de/docs/self-hosting.md

Hilf mir, ein Problem einzugrenzen.

- Frag mich zuerst, was ich beobachte und was ich erwartet hätte.
- Leite daraus die wahrscheinlichsten Ursachen ab, die zu dieser Quelle passen.
- Gib mir je Ursache EINEN Test, der sie bestätigt oder ausschließt.
- Sortiere so, dass der billigste Test zuerst kommt.

Rate nicht. Wenn die Quelle das Problem nicht abdeckt, sag mir, wo ich
weitersuchen sollte.
Hinweis zu den Quellen:
- Jede Seite dieser Dokumentation ist als Markdown abrufbar (dieselbe Adresse mit `.md`).
- Ein maschinenlesbarer Überblick aller öffentlichen Inhalte liegt unter `/llms.txt`.
- Falls du Zugriff auf den aYOUne-MCP-Server hast, kannst du damit gegen lebende Daten
  arbeiten statt gegen diese Momentaufnahme. Falls nicht, ignoriere diesen Punkt.
In einfachen Worten erklären Ohne Fachbegriffe, von Grund auf.
In ChatGPT öffnen 
Lies die folgende Dokumentation von tolinax UG und arbeite damit.

Diese Seite: https://ayoune.com/de/docs/self-hosting/troubleshooting.md
Die vollständige Sammlung: https://ayoune.com/de/docs/self-hosting.md

Erkläre den Inhalt so, dass ihn jemand ohne Vorwissen versteht.

- Beginne mit dem Zweck: wozu gibt es das überhaupt?
- Fachbegriffe beim ersten Vorkommen in einem Halbsatz erklären.
- Ein Alltags-Vergleich, wo er wirklich trägt — keiner, wo er hinkt.
- Am Ende: die drei Dinge, die man sich merken sollte.

Kürze nicht durch Weglassen von Einschränkungen. Eine Vereinfachung, die eine
Bedingung unterschlägt, ist eine Falschaussage.
Hinweis zu den Quellen:
- Jede Seite dieser Dokumentation ist als Markdown abrufbar (dieselbe Adresse mit `.md`).
- Ein maschinenlesbarer Überblick aller öffentlichen Inhalte liegt unter `/llms.txt`.
- Falls du Zugriff auf den aYOUne-MCP-Server hast, kannst du damit gegen lebende Daten
  arbeiten statt gegen diese Momentaufnahme. Falls nicht, ignoriere diesen Punkt.
Checkliste zum Abhaken Zum Mitgehen während der Umsetzung.
In ChatGPT öffnen 
Lies die folgende Dokumentation von tolinax UG und arbeite damit.

Diese Seite: https://ayoune.com/de/docs/self-hosting/troubleshooting.md
Die vollständige Sammlung: https://ayoune.com/de/docs/self-hosting.md

Mache daraus eine **abhakbare Checkliste** für die praktische Umsetzung.

- Je Punkt genau eine Handlung, im Imperativ.
- Reihenfolge so, dass kein Punkt eine spätere Voraussetzung braucht.
- Voraussetzungen und Stolperstellen als eingerückte Unterpunkte.
- Am Ende eine Abnahme: woran erkenne ich, dass alles richtig ist?
Hinweis zu den Quellen:
- Jede Seite dieser Dokumentation ist als Markdown abrufbar (dieselbe Adresse mit `.md`).
- Ein maschinenlesbarer Überblick aller öffentlichen Inhalte liegt unter `/llms.txt`.
- Falls du Zugriff auf den aYOUne-MCP-Server hast, kannst du damit gegen lebende Daten
  arbeiten statt gegen diese Momentaufnahme. Falls nicht, ignoriere diesen Punkt.
In mein Projekt einbauen Konkreter Code für meinen Anwendungsfall.
In ChatGPT öffnen 
Lies die folgende Dokumentation von tolinax UG und arbeite damit.

Diese Seite: https://ayoune.com/de/docs/self-hosting/troubleshooting.md
Die vollständige Sammlung: https://ayoune.com/de/docs/self-hosting.md

Hilf mir, das in mein Projekt einzubauen.

- Frag mich zuerst nach Sprache, Umgebung und dem, was ich erreichen will.
- Gib dann ein minimales, lauffähiges Beispiel — keine Auslassungs-Punkte.
- Benenne die Fehlerfälle, die ich abfangen muss, und wie sie sich zeigen.
- Nenne Grenzen: Zeitlimits, Mengenbegrenzungen, Berechtigungen.

Verwende ausschließlich das, was die Quelle wirklich beschreibt. Erfinde keine
Felder, Parameter oder Endpunkte — ein erfundener Aufruf kostet mich mehr Zeit,
als er spart.
Hinweis zu den Quellen:
- Jede Seite dieser Dokumentation ist als Markdown abrufbar (dieselbe Adresse mit `.md`).
- Ein maschinenlesbarer Überblick aller öffentlichen Inhalte liegt unter `/llms.txt`.
- Falls du Zugriff auf den aYOUne-MCP-Server hast, kannst du damit gegen lebende Daten
  arbeiten statt gegen diese Momentaufnahme. Falls nicht, ignoriere diesen Punkt.

War dieser Artikel hilfreich?

👎 Nein (0)
Kommentar hinterlassen