Troubleshooting | AI Engineering Wiki

📋 Auf einen Blick

Systematisches Debugging in 5 Schritten: Problem verstehen, Daten sammeln, Hypothese bilden, testen, dokumentieren. Wichtigste Tools: docker logs, docker stats, docker network inspect. Häufigste Ursachen: Port-Konflikte, OOM-Kills, Netzwerk-Isolation, fehlende Volumes. Immer Logs zuerst prüfen.

Wenn etwas nicht funktioniert, brauchst du einen systematischen Ansatz. Hier sind unsere bewährten Methoden.

Die 5 Schritte Methode

1. Problem verstehen

Was genau passiert? Wann tritt es auf? Was sollte passieren?

2. Daten sammeln

Logs anschauen, Fehlermeldungen notieren, Zeitstempel finden.

3. Hypothese bilden

Was ist die wahrscheinlichste Ursache? Nicht die seltenste.

4. Testen

Eine Änderung nach der anderen. Nicht mehrere auf einmal.

5. Dokumentieren

Was war das Problem? Wie wurde es gelöst? Für nächstes Mal.

Häufige Probleme Docker

Problem	Lösung
Container startet nicht	docker logs container_name
Port schon belegt	docker ps \| grep port
Out of Memory	docker stats
Network-Fehler	docker network ls
Volume-Fehler	docker volume ls

Wichtige Debug-Befehle

# Container-Logs
docker logs -f container_name
docker logs --tail 100 container_name

# Live-Stats
docker stats

# Alle Container
docker ps -a

# Netzwerk
docker network inspect bridge
docker network ls

# Volumes
docker volume ls
docker volume inspect volume_name

# Bash im Container
docker exec -it container_name /bin/bash

# Neustart
docker restart container_name

Docker Swarm Debugging

# Service-Status
docker service ls
docker service ps service_name

# Service-Logs
docker service logs -f service_name

# Service-Infos
docker service inspect service_name

# Nodes
docker node ls

# Cluster-Status
docker info

Log-Analyse

Logs sind dein wichtigstes Werkzeug:

Immer mit Timestamps - wann begann das Problem?
Nach ERROR und WARNING suchen
Kontext beachten - was passierte davor?
Stack Traces vollständig kopieren

Monitoring hilft

Mit Grafana + Prometheus siehst du Probleme früher:

CPU-Spitzen
Memory-Leaks
Container-Restarts
Network-Fehler

Ollama Troubleshooting

Problem	Ursache	Lösung
GPU nicht erkannt	nvidia-container-toolkit fehlt	`nvidia-smi` im Container prüfen
OOM bei großen Modellen	Nicht genug VRAM	Kleineres Modell oder Quantisierung (Q4_K_M)
Connection refused :11434	Ollama bindet nur auf localhost	`OLLAMA_HOST=0.0.0.0` setzen
Langsame Inferenz	CPU-Fallback statt GPU	`ollama ps` — prüfen ob GPU genutzt wird

# Ollama Debug-Befehle
# GPU-Status prüfen
docker exec ollama nvidia-smi

# Laufende Modelle anzeigen
docker exec ollama ollama ps

# Modell-Details (VRAM-Bedarf)
docker exec ollama ollama show llama3.2 --modelfile

# Ollama Logs
docker logs ollama --tail 50

# API Health-Check
curl http://localhost:11434/api/tags

n8n Troubleshooting

Problem	Ursache	Lösung
Workflows verschwunden	Volume nicht persistiert	Volume-Mount auf `/home/node/.n8n` prüfen
Webhook nicht erreichbar	WEBHOOK_URL falsch	`N8N_WEBHOOK_URL` korrekt setzen
DB-Verbindung fehlgeschlagen	PostgreSQL nicht erreichbar	Netzwerk und `DB_POSTGRESDB_HOST` prüfen

⚠️ Docker und OOM-Kills

Wenn ein Container plötzlich stoppt ohne Fehlermeldung in den Logs, wurde er wahrscheinlich vom Kernel wegen Speichermangel gekillt. Prüfe mit docker inspect container_name | grep OOMKilled und erhöhe das Memory-Limit oder reduziere die Last.

Checkliste bei Problemen

[ ] Logs geprüft?
[ ] Container läuft?
[ ] Ports frei?
[ ] Genug Ressourcen (RAM, VRAM, Disk)?
[ ] Netzwerk erreichbar?
[ ] Volumes korrekt gemountet?
[ ] Environment-Variablen gesetzt?

Quellen

Docker Docs: Logging — Container-Logs konfigurieren und lesen
Ollama Troubleshooting — Offizielle Fehlerbehandlung
n8n Environment Variables — Konfiguration und Debugging
Docker Docs: Swarm Services — Service-Debugging im Cluster

Troubleshooting Leitfaden