translate

Not in your language

This page is not yet available in en. You're reading the de version.

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.

Work with this page

Ready-made instructions for your AI tool. Copy, paste, go — the AI fetches the content itself via the address in the text.

Summarise the steps for me The essentials, in the right order.

Open in ChatGPT

Read the following documentation by tolinax UG and work with it.

This page: https://ayoune.com/en/docs/self-hosting/troubleshooting.md
The complete collection: https://ayoune.com/en/docs/self-hosting.md

Summarise the content for me.

- First, in two sentences: what is this about?
- Then the steps in the order I need to take them.
- One line per step, in plain language.
- At the end: what I should have ready beforehand.

Leave out nothing I need in order to actually finish.
A note on sources:
- Every page of this documentation is available as Markdown (the same address with `.md`).
- A machine-readable overview of all public content is at `/llms.txt`.
- If you have access to the aYOUne MCP server, you can work against live data
  instead of this snapshot. If not, ignore this point.

Help me set this up Step by step, asking me as you go.

Open in ChatGPT

Read the following documentation by tolinax UG and work with it.

This page: https://ayoune.com/en/docs/self-hosting/troubleshooting.md
The complete collection: https://ayoune.com/en/docs/self-hosting.md

Walk me through the setup step by step.

- First tell me what I need to have ready (access, data, time).
- Then take me through ONE step at a time. Wait for my "next".
- For each step, say how I can tell that it worked.
- If something goes wrong, ask me for the exact message instead of guessing.

If the instructions leave a point open, tell me so rather than inventing it.
A note on sources:
- Every page of this documentation is available as Markdown (the same address with `.md`).
- A machine-readable overview of all public content is at `/llms.txt`.
- If you have access to the aYOUne MCP server, you can work against live data
  instead of this snapshot. If not, ignore this point.

Help me with a problem Narrow down the cause instead of guessing.

Open in ChatGPT

Read the following documentation by tolinax UG and work with it.

This page: https://ayoune.com/en/docs/self-hosting/troubleshooting.md
The complete collection: https://ayoune.com/en/docs/self-hosting.md

Help me narrow down a problem.

- First ask me what I observe and what I expected instead.
- From that, derive the most likely causes consistent with this source.
- For each cause, give me ONE test that confirms or rules it out.
- Order them so the cheapest test comes first.

Do not guess. If the source does not cover the problem, tell me where I should
look next.
A note on sources:
- Every page of this documentation is available as Markdown (the same address with `.md`).
- A machine-readable overview of all public content is at `/llms.txt`.
- If you have access to the aYOUne MCP server, you can work against live data
  instead of this snapshot. If not, ignore this point.

Explain it in plain words No jargon, from the ground up.

Open in ChatGPT

Read the following documentation by tolinax UG and work with it.

This page: https://ayoune.com/en/docs/self-hosting/troubleshooting.md
The complete collection: https://ayoune.com/en/docs/self-hosting.md

Explain the content so that someone without prior knowledge understands it.

- Start with the purpose: why does this exist at all?
- Explain technical terms in half a sentence on first use.
- One everyday comparison where it genuinely holds — none where it limps.
- At the end: the three things worth remembering.

Do not shorten by dropping conditions. A simplification that hides a
prerequisite is a false statement.
A note on sources:
- Every page of this documentation is available as Markdown (the same address with `.md`).
- A machine-readable overview of all public content is at `/llms.txt`.
- If you have access to the aYOUne MCP server, you can work against live data
  instead of this snapshot. If not, ignore this point.

A checklist to tick off To follow along while you do it.

Open in ChatGPT

Read the following documentation by tolinax UG and work with it.

This page: https://ayoune.com/en/docs/self-hosting/troubleshooting.md
The complete collection: https://ayoune.com/en/docs/self-hosting.md

Turn this into a **tick-off checklist** for practical use.

- Exactly one action per item, in the imperative.
- Order it so that no item depends on a later prerequisite.
- Prerequisites and pitfalls as indented sub-items.
- End with an acceptance step: how do I know everything is right?
A note on sources:
- Every page of this documentation is available as Markdown (the same address with `.md`).
- A machine-readable overview of all public content is at `/llms.txt`.
- If you have access to the aYOUne MCP server, you can work against live data
  instead of this snapshot. If not, ignore this point.

Build it into my project Concrete code for my use case.

Open in ChatGPT

Read the following documentation by tolinax UG and work with it.

This page: https://ayoune.com/en/docs/self-hosting/troubleshooting.md
The complete collection: https://ayoune.com/en/docs/self-hosting.md

Help me build this into my project.

- First ask me about language, environment and what I am trying to achieve.
- Then give a minimal, runnable example — no ellipses standing in for code.
- Name the error cases I must handle and how they surface.
- State the limits: timeouts, quotas, permissions.

Use only what the source actually describes. Do not invent fields, parameters
or endpoints — an invented call costs me more time than it saves.
A note on sources:
- Every page of this documentation is available as Markdown (the same address with `.md`).
- A machine-readable overview of all public content is at `/llms.txt`.
- If you have access to the aYOUne MCP server, you can work against live data
  instead of this snapshot. If not, ignore this point.

Was this article helpful?

👎 No (0)