Container startet nicht - systematische Diagnose in Docker

Ein Container startet nicht und du weißt nicht warum — diese Schritt-für-Schritt-Diagnose führt dich systematisch zur Ursache.

Schritt 1: Container-Status prüfen

docker ps -a

Der wichtigste Wert ist die Spalte STATUS. Ein gestoppter Container zeigt Exited (CODE) — der Exit-Code ist der erste Hinweis auf die Fehlerursache.

Schritt 2: Logs lesen

docker logs containername
docker logs --tail 50 containername

Die letzten Zeilen enthalten fast immer die eigentliche Fehlermeldung. --tail 50 begrenzt die Ausgabe auf die letzten 50 Zeilen, was bei gesprächigen Containern sinnvoll ist.

Schritt 3: Container inspizieren

docker inspect containername

Die relevanten Abschnitte sind Config (Umgebungsvariablen, Entrypoint, Cmd) und State (ExitCode, OOMKilled, Error). Gezielt abfragen:

docker inspect containername --format '{{.State}}'
docker inspect containername --format '{{.State.ExitCode}}'

Schritt 4: Interaktiv debuggen

Wenn der Container sofort crasht, lässt er sich nicht mit exec betreten. Stattdessen: Image direkt mit einer Shell starten und den Entrypoint überschreiben.

docker run -it --entrypoint sh imagename
# Bei Alpine-Images
docker run -it --entrypoint /bin/sh imagename

Jetzt kann man manuell prüfen, ob Dateien vorhanden sind, Umgebungsvariablen korrekt gesetzt sind und der eigentliche Startbefehl von Hand ausgeführt werden.

Schritt 5: Port-Konflikte prüfen

ss -tlnp | grep :8080
# oder
lsof -i :8080

Ein bereits belegter Port verhindert den Container-Start. Lösung: Host-Port in der Compose-Datei ändern (HOST:CONTAINER).

Schritt 6: Volume-Berechtigungen prüfen

docker run -it --entrypoint sh imagename
ls -la /app/data

Bind-Mounts erben die Berechtigungen vom Host. Wenn der Container-Prozess als User 1000 läuft, aber das Host-Verzeichnis root gehört, schlägt der Start fehl.

Exit-Codes und ihre Bedeutung

| Code | Bedeutung |
|------|-----------|
| 0 | Prozess sauber beendet (kein Fehler, aber kein Restart-Kandidat ohne unless-stopped) |
| 1 | Allgemeiner Applikationsfehler — Logs prüfen |
| 125 | Docker-eigener Fehler (falsches Flag, unbekannter Befehl) |
| 126 | Entrypoint nicht ausführbar — Berechtigungsproblem |
| 127 | Befehl nicht gefunden — falscher Entrypoint oder PATH falsch |
| 137 | SIGKILL empfangen — meistens OOMKilled (zu wenig RAM) |
| 139 | Segmentation Fault — fehlerhafte Binary oder falsche Architektur (z. B. ARM-Image auf x86) |

OOMKilled erkennen

docker inspect containername --format '{{.State.OOMKilled}}'

Gibt true zurück, wenn der Kernel den Container wegen Speichermangels beendet hat. Lösung: Memory-Limit erhöhen oder Swap aktivieren.

deploy:
  resources:
    limits:
      memory: 512m

Zusammenfassung

Der schnellste Diagnosepfad: docker ps -a → Exit-Code notieren → docker logs → Fehler lesen → bei Bedarf docker inspect → interaktiv mit überschriebenem Entrypoint debuggen. In 90 % der Fälle reicht die Log-Ausgabe allein.