Zum Inhalt springen
SONOYA.com
Selfhosting & Web

Docker-Container startet nicht: Logs und Exit-Codes

Docker-Container hängt in „Restarting“ oder beendet sich sofort? So findest Du mit Logs, Exit-Code und Healthcheck die Ursache und behebst sie.

Von

Docker-Wal-Symbol auf dunklem Verlauf als Sinnbild für die Fehlersuche an einem Container, der nicht startet oder ständig neu startet

Du startest einen Dienst mit docker compose up -d, alles sieht gut aus, und trotzdem ist die Weboberfläche nicht erreichbar. Ein Blick in die Übersicht zeigt dann Restarting (1), Exited (137) oder unhealthy. Docker verrät Dir in fast jedem dieser Fälle sehr genau, was schiefgeht, Du musst nur an den richtigen drei Stellen nachsehen: im Status, in den Logs und im Exit-Code. Diese Anleitung geht die Stellen der Reihe nach durch und ordnet danach die häufigsten Ursachen ihren typischen Fehlermeldungen zu.

Alle Befehle beziehen sich auf die aktuelle Docker Engine mit dem Compose-Plugin (docker compose, Compose v5) unter Linux, sie funktionieren genauso auf dem Raspberry Pi und mit Docker Desktop am Mac. Ich nenne den Dienst in den Beispielen app; ersetze ihn durch den Namen aus Deiner compose.yaml.

Schritt 1: Den Status richtig lesen

Wechsle in das Verzeichnis mit Deiner compose.yaml und lass Dir alle Container des Projekts anzeigen, auch die beendeten:

Code
docker compose ps -a

Ohne -a zeigt Compose nur laufende Container, und ein abgestürzter Dienst taucht dann gar nicht erst auf. Entscheidend ist die Spalte STATUS. Sie zeigt meist einen dieser Zustände, und jeder deutet in eine andere Richtung:

  • Up 5 minutes heißt, der Container läuft. Erreichst Du den Dienst trotzdem nicht, liegt es meist an der Portfreigabe oder an der Anwendung selbst, nicht an Docker.
  • Up 5 minutes (unhealthy) heißt, der Prozess läuft, aber der eingebaute Healthcheck schlägt fehl. Dazu mehr in Schritt 4.
  • Exited (1) 2 minutes ago heißt, der Prozess hat sich beendet und wird nicht neu gestartet. Die Zahl in Klammern ist der Exit-Code.
  • Restarting (1) 3 seconds ago heißt, der Container stürzt ab und Docker startet ihn wegen der Restart-Policy immer wieder. Auch hier steht der letzte Exit-Code in Klammern.
  • Created heißt, Docker hat den Container angelegt, konnte ihn aber nicht starten. Die Ursache steht dann in der Ausgabe von docker compose up, nicht in den Logs.

In der Spalte NAME siehst Du außerdem den vollständigen Containernamen, etwa meinprojekt-app-1. Den brauchst Du für die Befehle, die direkt mit docker statt mit docker compose arbeiten.

Schritt 2: Die Logs ansehen, bevor Du irgendetwas änderst

Die eigentliche Fehlermeldung steht fast immer in den letzten Zeilen, die der Prozess vor seinem Ende ausgegeben hat:

Code
docker compose logs --tail 50 --timestamps app

--tail 50 begrenzt die Ausgabe auf die letzten 50 Zeilen, und --timestamps stellt jeder Zeile die Uhrzeit voran. Gerade bei einem Container in der Restart-Schleife ist das wichtig: Docker hängt die Ausgabe jedes neuen Startversuchs an dieselbe Logdatei an, sodass Du dieselbe Meldung zehnmal untereinander siehst. Anhand der Zeitstempel erkennst Du, wo ein Durchlauf endet und der nächste beginnt, und die letzte Zeile vor dem Sprung ist die interessante.

Wenn Du live zusehen willst, wie der Container startet, hängst Du -f an:

Code
docker compose logs -f --tail 20 app

Mit Strg + C beendest Du nur die Anzeige, der Container läuft davon unberührt weiter.

Die Restart-Schleife anhalten

Eine Restart-Policy wie restart: unless-stopped ist im Betrieb sinnvoll, bei der Fehlersuche stört sie. Docker wartet vor jedem neuen Versuch doppelt so lange wie zuvor, beginnend bei 100 Millisekunden und begrenzt auf eine Minute. Der Container ist dadurch mal kurz da und mal weg, und Befehle wie docker exec scheitern, weil sie genau den Moment zwischen zwei Versuchen erwischen. Halte die Schleife deshalb an:

Code
docker update --restart=no meinprojekt-app-1

Ersetze meinprojekt-app-1 durch den Namen aus Schritt 1. Der Container läuft nach dem nächsten Absturz nicht wieder an und bleibt mit seinem Exit-Code stehen. Keine Sorge, das ändert nichts an Deiner compose.yaml: Beim nächsten docker compose up -d legt Compose den Container mit der dort eingetragenen Policy neu an.

Schritt 3: Den Exit-Code deuten

Den Exit-Code siehst Du schon im Status, genauer liest Du ihn zusammen mit der Information, ob der Kernel den Prozess wegen Speichermangels beendet hat, so aus:

Code
docker inspect --format 'Exit-Code: {{.State.ExitCode}}, OOM: {{.State.OOMKilled}}, Fehler: {{.State.Error}}' meinprojekt-app-1

Die Ausgabe sieht dann etwa so aus: Exit-Code: 137, OOM: true, Fehler: . Die Codes bedeuten Folgendes:

Exit-CodeBedeutungTypische Ursache
0Prozess hat sich regulär beendetDas Image führt einen einmaligen Befehl aus, oder der Hauptprozess läuft im Hintergrund statt im Vordergrund
1allgemeiner Fehler der AnwendungKonfigurationsfehler, fehlende Variable, Datenbank nicht erreichbar; die Logs sagen, welcher
125Docker selbst meldet einen Fehler, bevor der Prozess startetfalsche Option beim Aufruf, ungültiger Mount
126Startbefehl gefunden, aber nicht ausführbarSkript ohne Ausführungsrecht, Pfad zeigt auf einen Ordner
127Startbefehl nicht gefundenTippfehler in command oder entrypoint, Programm fehlt im Image
137Prozess wurde mit SIGKILL beendet (128 + 9)Speichermangel (OOM: true) oder ein Stopp, auf den der Prozess nicht rechtzeitig reagiert hat
139Speicherzugriffsfehler (128 + 11)Absturz im Programm, etwa durch eine defekte Bibliothek oder ein inkompatibles Image
143Prozess wurde mit SIGTERM beendet (128 + 15)normales Herunterfahren durch docker stop oder ein Update

Die Bedeutung von 125, 126 und 127 ist in der Docker-Doku zu docker run festgelegt, alle anderen Codes reicht Docker unverändert vom Prozess im Container durch. Werte über 128 heißen immer: Der Prozess wurde durch ein Signal beendet, und die Differenz zu 128 ist die Signalnummer.

Sonderfall 137: Speicher oder Stopp?

Steht bei OOM ein true, hat der Kernel den Prozess wegen Speichermangels beendet. Unter Linux bestätigt das Kernel-Log den Verdacht:

Code
sudo dmesg -T | grep -iE "out of memory|killed process"

Taucht dort eine Zeile mit Killed process und dem Namen Deines Programms auf, braucht der Container mehr Arbeitsspeicher, als er bekommt. Prüf in der compose.yaml, ob unter deploy.resources.limits.memory oder mem_limit ein zu knappes Limit steht, und schau mit free -h, wie viel der Rechner überhaupt frei hat. Auf einem Raspberry Pi mit 1 oder 2 GB ist das bei Datenbanken und Java-Anwendungen schnell erreicht.

Steht dagegen OOM: false, hat jemand den Container gestoppt, und der Prozess hat das freundliche SIGTERM ignoriert. Docker wartet dann zehn Sekunden und beendet ihn hart. Das ist kein Startfehler, sondern ein Hinweis, dass das Image Signale nicht sauber verarbeitet.

Schritt 4: Wenn der Healthcheck „unhealthy“ meldet

Ein Container mit (unhealthy) läuft, aber der Prüfbefehl aus dem Image oder aus Deiner compose.yaml schlägt fehl. Docker speichert die letzten Ergebnisse dieses Befehls samt Ausgabe:

Code
docker inspect --format '{{json .State.Health}}' meinprojekt-app-1

Die Ausgabe ist JSON. Lesbar wird sie, wenn Du sie an jq weiterreichst, wie es die Anleitung jq: JSON im Terminal lesen, filtern und umbauen zeigt. Interessant sind FailingStreak, also die Zahl der Fehlschläge in Folge, und im Feld Log die Output-Texte der letzten Prüfungen. Drei Muster begegnen Dir dort immer wieder:

  1. exec: "curl": executable file not found in $PATH: Der Healthcheck ruft curl auf, das im schlanken Image gar nicht installiert ist. Nimm ein Werkzeug, das im Image vorhanden ist (oft wget), oder den Prüfbefehl, den der Hersteller in seiner Doku empfiehlt.
  2. Connection refused: Die Anwendung hört auf einem anderen Port oder auf einer anderen Adresse als der Healthcheck prüft. Vergleiche den Port im Prüfbefehl mit dem, den die Anwendung im Log beim Start nennt, nicht mit dem nach außen freigegebenen Port.
  3. Der Container wird kurz nach dem Start unhealthy und später healthy: Die Anwendung braucht länger zum Starten, als der Healthcheck ihr Zeit lässt. Erhöhe start_period, damit Fehlschläge in der Startphase nicht zählen.

Ein unhealthy-Status allein beendet den Container übrigens nicht. Er wird erst zum Problem, wenn ein anderer Dienst mit depends_on und condition: service_healthy auf ihn wartet und deshalb gar nicht erst startet.

Schritt 5: In den Container hineinsehen

Beendet sich der Container so schnell, dass Du mit docker exec nie hineinkommst, startest Du eine Kopie des Dienstes mit einer Shell statt der Anwendung:

Code
docker compose run --rm --entrypoint sh app

Compose legt dafür einen frischen Container mit denselben Volumes, Umgebungsvariablen und Netzwerken an, ersetzt aber den Startbefehl durch sh. --rm entfernt ihn nach dem Verlassen wieder. Ports gibt docker compose run standardmäßig nicht frei, so kommt sich die Kopie nicht mit einem eventuell noch laufenden Original in die Quere. In der Shell prüfst Du jetzt in Ruhe, ob Dateien da sind, welche Rechte sie haben und ob der eigentliche Startbefehl von Hand eine verständlichere Fehlermeldung liefert. Enthält das Image keine sh, scheitert der Befehl mit executable file not found. Das betrifft vor allem sehr schlanke „distroless“-Images, bei denen Dir dann nur die Logs bleiben.

Die häufigsten Ursachen und ihre Fehlermeldungen

Mit Logs und Exit-Code in der Hand findest Du Deine Ursache meist in dieser Liste wieder.

Port bereits belegt

docker compose up bricht mit Bind for 0.0.0.0:8080 failed: port is already allocated oder address already in use ab, und der Container bleibt im Status Created stehen, ohne je zu laufen. Ein anderer Container oder Dienst nutzt den Port schon. Unter Linux findest Du ihn so:

Code
sudo ss -ltnp | grep ':8080'

Am Mac hilft Dir die Anleitung Port belegt am Mac: „Address already in use“ lösen weiter. Ändere dann entweder den linken Teil der Portzuordnung in der compose.yaml ("8081:8080") oder beende den anderen Dienst.

Keine Schreibrechte im Volume

Die Logs zeigen Permission denied, EACCES oder read-only file system, meist mit Exit-Code 1. Das passiert typischerweise bei Bind Mounts wie ./data:/var/lib/app, wenn der Ordner auf dem Host root gehört, die Anwendung im Container aber als normaler Benutzer läuft. Unter welcher Benutzer-ID das Image arbeitet, zeigt Dir:

Code
docker compose run --rm --entrypoint id app

Steht dort zum Beispiel uid=1000, vergleichst Du das mit dem Besitzer des Ordners auf dem Host:

Code
ls -ln ./data

Passen die Zahlen nicht zusammen, übergibst Du den Ordner an diese Benutzer-ID:

Code
sudo chown -R 1000:1000 ./data

Ersetze 1000:1000 durch die Werte aus der id-Ausgabe. Manche Images starten als root und wechseln erst später den Benutzer; dann nennt die Doku des Images die erwartete ID, oft über Variablen wie PUID und PGID.

Fehlende Variable aus der .env

Die Anwendung meldet ein fehlendes Passwort oder eine leere Datenbankadresse, und beim docker compose up erscheint eine Warnung wie The "DB_PASSWORD" variable is not set. Defaulting to a blank string. Compose hat die Variable nicht gefunden und einen leeren Wert eingesetzt. Was Compose tatsächlich verwendet, siehst Du mit:

Code
docker compose config

Der Befehl gibt die fertig ausgewertete Konfiguration aus, mit allen eingesetzten Werten. Steht dort hinter DB_PASSWORD nichts, liegt die .env nicht im Projektordner, ist anders benannt oder enthält einen Tippfehler. Damit das nie wieder unbemerkt passiert, schreibst Du Pflichtvariablen in der compose.yaml als ${DB_PASSWORD:?DB_PASSWORD fehlt in der .env}. Compose bricht dann mit genau dieser Meldung ab, statt den Container mit einem leeren Wert zu starten. Wie Compose .env-Dateien liest, erklärt die Anleitung Docker Compose verstehen: Volumes, Netzwerke und .env ausführlich.

Falsche Prozessorarchitektur

Im Log steht nur eine einzige Zeile wie exec /usr/local/bin/docker-entrypoint.sh: exec format error, und der Container beendet sich sofort wieder. Das Image wurde für eine andere CPU gebaut, etwa nur für amd64, während Dein Raspberry Pi arm64 braucht. Vergleiche beides:

Code
uname -m
docker image inspect --format '{{.Os}}/{{.Architecture}}' meinimage:latest

uname -m zeigt aarch64 für einen 64-Bit-Pi oder einen Mac mit Apple-Chip und x86_64 für einen normalen PC oder Server. Ersetze meinimage:latest durch das Image aus Deiner compose.yaml. Gibt es vom Hersteller kein Image für Deine Architektur, ist ein anderes Image oder ein anderer Rechner die saubere Lösung; Emulation über platform: linux/amd64 funktioniert nur mit eingerichteter Emulation und ist spürbar langsam. Worauf Du auf dem Pi beim Auswählen von Images achtest, steht in Docker auf dem Raspberry Pi installieren und nutzen.

Die Datenbank ist noch nicht bereit

Die App stirbt beim Start mit connection refused zur Datenbank, startet ein paarmal neu und läuft irgendwann. Hier wartet depends_on nur darauf, dass der Datenbank-Container gestartet ist, nicht darauf, dass die Datenbank Verbindungen annimmt. Die Lösung ist ein Healthcheck an der Datenbank und condition: service_healthy an der App, so wie es das Beispiel im Compose-Grundlagenartikel zeigt.

Woran Du erkennst, dass es behoben ist

Starte das Projekt nach Deiner Korrektur neu:

Code
docker compose up -d

Warte eine Minute und ruf docker compose ps noch einmal auf. Steht beim Dienst Up mit wachsender Laufzeit und, falls ein Healthcheck definiert ist, (healthy), ist der Fehler behoben. Die Laufzeit ist das wichtigere Signal: Ein Container, der nach einer Minute immer noch Up 3 seconds zeigt, steckt weiter in einer Schleife. Bleibt ein Fehler rätselhaft, lohnt ein Blick in das Log des Docker-Dienstes selbst mit journalctl -u docker, wie es journalctl: Fehler unter Linux in den Logs finden erklärt. Und falls die Logs Deiner Container über Monate auf viele Gigabyte angewachsen sind, hilft Dir Docker belegt zu viel Speicher: sicher aufräumen dabei, ihre Größe dauerhaft zu begrenzen.

Weiterlesen.