---
title: "Troubleshooting"
source: "https://ayoune.com/en/docs/self-hosting/troubleshooting"
tenant: "tolinax UG"
brand: "aYOUne"
collection: "Self-Hosting"
language: "en"
retrieved: "2026-09-11T17:19:38.879Z"
platform: "aYOUne — https://ayoune.com"
generator: "aYOUne Doku-Export"
contact: "info@tolinax.com"
license: "Alle Rechte vorbehalten. Weitergabe nur mit Quellenangabe."
---

# 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

```bash
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

```bash
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

```text
[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:

```text
[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:

```bash
helm upgrade api-crm tolinax/node --set probes.enabled=true ...
```

## Logs lesen

aYOUne loggt strukturiert in `ayounelogs` (MongoDB-Collection mit ~1h TTL). Live-Tailing:

```bash
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

```bash
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`:

```bash
ay db explain consumers '{"_status":"active"}'
```

## Wenn nichts hilft

Dump erstellen, an Tolinax-Support:

```bash
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