Container crasht sofort - Exit-Codes verstehen und Fehler beheben

Ein Container startet und ist sofort wieder weg — der Exit-Code sagt dir, was schiefgelaufen ist.

Exit-Code auslesen

docker ps -a
# Spalte STATUS: "Exited (137)" z. B.

# Oder gezielt:
docker inspect containername --format '{{.State.ExitCode}}'

Exit-Codes im Detail

Exit Code 0 — sauber beendet

Der Prozess hat sich selbst regulär beendet. Kein Fehler — aber wenn der Container dauerhaft laufen soll, fehlt restart: unless-stopped:

services:
  myapp:
    restart: unless-stopped

Ohne Restart-Policy startet Docker einen Container mit Exit 0 nicht neu.

Exit Code 1 — Applikationsfehler

Der häufigste Code. Die Anwendung selbst hat einen Fehler geworfen und ist abgestürzt. Ursachen: fehlende Umgebungsvariable, Datenbankverbindung schlägt fehl, Konfigurationsdatei nicht vorhanden.

docker logs containername
# Letzte Zeilen zeigen den Fehler

Exit Code 137 — OOMKilled

Der Linux-Kernel hat den Prozess via SIGKILL beendet — in Docker fast immer wegen Speichermangels.

docker inspect containername --format '{{.State.OOMKilled}}'
# true = OOMKilled

Lösung: Memory-Limit erhöhen oder die Anwendung optimieren:

deploy:
  resources:
    limits:
      memory: 1g

Alternativ Swap auf dem Host aktivieren — Docker-Container können Host-Swap nutzen.

Exit Code 139 — Segmentation Fault

Der Prozess hat auf ungültigen Speicher zugegriffen. Mögliche Ursachen:

• Falsches CPU-Architektur: ARM-Image auf x86-Host (oder umgekehrt)
• Korruptes Binary im Image
• Bug in nativem Code (C/C++)

# Architektur des Images prüfen
docker inspect imagename --format '{{.Architecture}}'

# Host-Architektur
uname -m

Exit Code 126 — Permission denied

Der Entrypoint-Befehl ist nicht ausführbar:

docker run --entrypoint sh imagename -c "ls -la /entrypoint.sh"
# Wenn nicht executable: chmod +x fehlte im Dockerfile

Fix im Dockerfile:

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

Exit Code 127 — Command not found

Der im ENTRYPOINT oder CMD angegebene Befehl existiert nicht im Container:

# Interaktiv prüfen
docker run -it --entrypoint sh imagename
which mycommand
echo $PATH

Häufige Ursache: falsch geschriebener Befehl im Dockerfile oder ein Binary das auf dem Build-System vorhanden war, aber nicht ins Image kopiert wurde.

Interaktiv debuggen

Wenn der Container sofort crasht, hilft der interaktive Modus mit überschriebenem Entrypoint:

docker run -it --entrypoint sh imagename
# Jetzt manuell den eigentlichen Startbefehl ausführen

Bei Images ohne Shell (Distroless):

# Debug-Variante des Images nutzen
docker run -it imagename:debug sh

State vollständig auslesen

docker inspect containername --format '{{json .State}}' | python3 -m json.tool

Gibt ExitCode, OOMKilled, Error, StartedAt, FinishedAt übersichtlich aus.

Zusammenfassung

| Exit Code | Bedeutung | Erste Maßnahme |
|-----------|-----------|----------------|
| 0 | Sauber beendet | restart: unless-stopped hinzufügen |
| 1 | App-Fehler | docker logs lesen |
| 137 | OOMKilled | Memory-Limit erhöhen |
| 139 | Segfault | Architektur prüfen, Image neu bauen |
| 126 | Entrypoint nicht ausführbar | chmod +x im Dockerfile |
| 127 | Befehl nicht gefunden | Entrypoint-Pfad und PATH prüfen |