Troubleshooting

Sortiert nach Symptom. Für jeden Eintrag: Diagnose-Befehl(e), häufige Ursachen, konkrete Fixes.

Container starten nicht

Diagnose

cd /opt/vesana
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs --tail 100
docker compose -f docker-compose.prod.yml logs api worker --tail 200

Häufige Ursachen

Ursache	Anzeichen	Fix
Postgres mountet bestehendes Volume mit anderer Postgres-Version	pg_data version mismatch im Log	docker compose down, docker volume rm vesana_pgdata, frisch starten (Datenverlust!) — oder altes Postgres-Image wiederherstellen
Init-Container scheitert an Migration	Migration X failed: …	Logs prüfen, Migrations-Datei reparieren, neu starten
.env fehlerhaft (z. B. BASE_URL ohne https://)	API-Container crasht beim Boot	.env korrigieren, docker compose up -d
Port 80/443 belegt	bind: address already in use	anderen Service stoppen oder HTTP_PORT/HTTPS_PORT in .env ändern
Disk voll	Container starten, sterben sofort	df -h, Logs/Backups aufräumen

Wizard nicht erreichbar

Diagnose

curl -kI https://deine-domain.tld/setup
docker compose -f /opt/vesana/docker-compose.prod.yml logs frontend nginx
nslookup deine-domain.tld

Häufige Ursachen

• DNS falsch — A-Record zeigt nicht auf den Server
• Cert-Beantragung gescheitert — Port 80 nicht offen oder DNS noch nicht propagiert; Browser-Warnung akzeptieren oder Cert manuell setzen
• nginx-Container hängt — docker compose restart nginx

Login klappt nicht

Diagnose

docker compose -f /opt/vesana/docker-compose.prod.yml logs api --tail 50 | grep -i auth

Häufige Ursachen

Ursache	Anzeichen	Fix
2FA-Code kommt nicht	SMTP nicht erreichbar	SMTP-Konfig prüfen, Test-Mail im Admin
Falsches Passwort	401 in Logs	Passwort-Reset via Mail-Link
Account inaktiv	„Account deactivated"	Admin: User aktivieren
Server-Zeit falsch	„token not yet valid / expired"	NTP einrichten
Frontend cached alte API-URL	nach Domain-Wechsel	Browser-Cache leeren, Service-Worker neu

Agent meldet sich nicht

Diagnose

Auf der Agent-Maschine:

# Linux
sudo systemctl status vesana-agent
sudo journalctl -u vesana-agent --since '5 minutes ago' -n 100

# Manueller Vordergrund-Run, zeigt direkten Output
sudo /usr/local/bin/vesana-agent --config /etc/vesana-agent/config.yaml

REM Windows
sc.exe query VesanaAgent
"C:\Program Files\Vesana\Agent\vesana-agent.exe" --config "C:\ProgramData\Vesana\Agent\config.yaml"

Häufige Fehlermeldungen

Log-Zeile	Ursache	Fix
dial tcp: lookup …: no such host	DNS	DNS-Resolver prüfen, ggf. /etc/resolv.conf
x509: certificate signed by unknown authority	TLS-Cert	echtes Cert oder Cert ins System-Trust-Store, sonst --insecure in Agent-Config
401 Unauthorized	Token falsch oder widerrufen	Token in der UI neu erzeugen, Config aktualisieren, Service neu starten
403 Forbidden	Token gehört zu einem anderen Host (durch DB-Reset?)	Token neu erzeugen
connection refused	Server-Service nicht erreichbar	Server-Health prüfen, Port-Forwarding
Auto-Update klemmt	VERSION-Datei vs. Binary inkonsistent	siehe Agent-Versionierung

Checks bleiben NO_DATA

Diagnose

In der UI: Service-Detail → Letzter Check-Versuch + Letzte Result-Zeit.

Häufige Ursachen

Ursache	Fix
Agent / Collector down	siehe Agent meldet sich nicht
Service nicht in Agent-/Collector-Config	Config-Refresh-Intervall (5 min Agent / 60 s Collector) abwarten oder manuell triggern
Falsche host_id / service_id Bindung	DB-Reset hinter dir? Token neu erzeugen
Receiver hat den Stream-Eintrag nicht akzeptiert	Receiver-Logs prüfen — meist INVALID_TOKEN oder Stream-Voll
Worker hängt	docker compose logs worker und ggf. neu starten

AI antwortet nicht

Diagnose

# Provider-Test in der UI: Admin → AI → Test connection
docker compose logs ollama --tail 50    # bei lokalem Ollama

Häufige Ursachen

Provider	Ursache	Fix
Ollama	Modell nicht installiert	Admin → AI → Modell installieren
Ollama	GPU nicht aktiv	nvidia-smi, nvidia-container-toolkit checken
Ollama	OOM bei zu großem Modell	kleineres Modell nehmen oder OLLAMA_KEEP_ALIVE=5m
Anthropic	API-Key abgelaufen	neuen Key generieren, einsetzen
Anthropic	Rate-Limit	Status der Anthropic-API prüfen
Extern	falsche URL / falsches Schema	URL in Admin → AI korrigieren

Push kommt nicht an

Diagnose

docker compose logs api | grep -i firebase

Häufige Ursachen

Ursache	Fix
Kein Firebase-Service-Account-Key	Admin → Push → Firebase-Key hochladen
Mobile-App nicht eingeloggt	App neu öffnen, einloggen
User hat Push-Channel pausiert (User-Pref)	App-Settings → Benachrichtigungen prüfen
Severity-Filter im Channel zu restriktiv	Channel auf „WARN+" stellen statt nur CRIT
Test-Push aus Channel funktioniert nicht	Audit-Log: was sagt Firebase-API?
FCM-Token läuft ab (sehr selten)	App neu installieren / Token neu registrieren

Update läuft nicht durch

Diagnose

docker compose logs updater --tail 100
docker compose logs init --tail 100

Häufige Ursachen

Ursache	Fix
Migration scheitert	Logs prüfen, manuell beheben (z. B. fehlende Permissions auf neue Tabellen), Update neu anstoßen
Image-Pull fehlgeschlagen	ghcr.io nicht erreichbar oder Registry-Credentials abgelaufen
Health-Check timeout	Service braucht länger als 90 s — kann an großem DB-Migration liegen, in .env Timeout erhöhen
Auto-Rollback ausgelöst	Health-Check failte; Logs sagen warum, Original-Version läuft weiter

Pipeline-Health rot

Diagnose

/admin/system → System-Tab zeigt was rot ist.

Häufige Ursachen

Symptom	Maßnahme
Stream-Pending steigt monoton	Worker hochskalieren — WORKER_REPLICAS erhöhen
Insert-Rate gefallen	DB-Engpass — Long-Running-Queries killen, vacuum
DB-Disk fast voll	Retention senken, TimescaleDB-Compression manuell triggern
AI-Latency hoch	kleineres Modell oder Provider tauschen
Worker-Lag hoch	WORKER_CONCURRENCY hoch, mehr WORKER_REPLICAS

Details: System-Health, Skalierung.

Diagnose-Bundle erstellen

Für Support:

sudo /opt/vesana/scripts/diagnose.sh > vesana-diag-$(date +%Y%m%d).txt

Das Script sammelt:

• docker compose ps
• docker compose logs --tail 500 pro Service
• df -h, free -m, uptime
• pg_stat_activity Top-10
• Redis-INFO

In das Bundle gehen keine Inhalte aus DB-Tabellen — sicher zum Versenden.

Anschluss

• FAQ
• System-Health
• Updates