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 Nathan Base
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:
docker compose ps -aOhne -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 minutesheiß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 agoheißt, der Prozess hat sich beendet und wird nicht neu gestartet. Die Zahl in Klammern ist der Exit-Code.Restarting (1) 3 seconds agoheiß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.Createdheißt, Docker hat den Container angelegt, konnte ihn aber nicht starten. Die Ursache steht dann in der Ausgabe vondocker 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:
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:
docker compose logs -f --tail 20 appMit 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:
docker update --restart=no meinprojekt-app-1Ersetze 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:
docker inspect --format 'Exit-Code: {{.State.ExitCode}}, OOM: {{.State.OOMKilled}}, Fehler: {{.State.Error}}' meinprojekt-app-1Die Ausgabe sieht dann etwa so aus: Exit-Code: 137, OOM: true, Fehler: . Die Codes bedeuten Folgendes:
| Exit-Code | Bedeutung | Typische Ursache |
|---|---|---|
0 | Prozess hat sich regulär beendet | Das Image führt einen einmaligen Befehl aus, oder der Hauptprozess läuft im Hintergrund statt im Vordergrund |
1 | allgemeiner Fehler der Anwendung | Konfigurationsfehler, fehlende Variable, Datenbank nicht erreichbar; die Logs sagen, welcher |
125 | Docker selbst meldet einen Fehler, bevor der Prozess startet | falsche Option beim Aufruf, ungültiger Mount |
126 | Startbefehl gefunden, aber nicht ausführbar | Skript ohne Ausführungsrecht, Pfad zeigt auf einen Ordner |
127 | Startbefehl nicht gefunden | Tippfehler in command oder entrypoint, Programm fehlt im Image |
137 | Prozess wurde mit SIGKILL beendet (128 + 9) | Speichermangel (OOM: true) oder ein Stopp, auf den der Prozess nicht rechtzeitig reagiert hat |
139 | Speicherzugriffsfehler (128 + 11) | Absturz im Programm, etwa durch eine defekte Bibliothek oder ein inkompatibles Image |
143 | Prozess 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:
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:
docker inspect --format '{{json .State.Health}}' meinprojekt-app-1Die 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:
exec: "curl": executable file not found in $PATH: Der Healthcheck ruftcurlauf, das im schlanken Image gar nicht installiert ist. Nimm ein Werkzeug, das im Image vorhanden ist (oftwget), oder den Prüfbefehl, den der Hersteller in seiner Doku empfiehlt.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.- Der Container wird kurz nach dem Start
unhealthyund späterhealthy: Die Anwendung braucht länger zum Starten, als der Healthcheck ihr Zeit lässt. Erhöhestart_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:
docker compose run --rm --entrypoint sh appCompose 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:
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:
docker compose run --rm --entrypoint id appSteht dort zum Beispiel uid=1000, vergleichst Du das mit dem Besitzer des Ordners auf dem Host:
ls -ln ./dataPassen die Zahlen nicht zusammen, übergibst Du den Ordner an diese Benutzer-ID:
sudo chown -R 1000:1000 ./dataErsetze 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:
docker compose configDer 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:
uname -m
docker image inspect --format '{{.Os}}/{{.Architecture}}' meinimage:latestuname -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:
docker compose up -dWarte 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.
-
Selfhosting & WebDocker Compose verstehen: Volumes, Netzwerke und .env
Docker Compose verständlich erklärt: Named Volume oder Bind Mount, Dienstnamen als Hostnamen, .env-Variablen, Healthchecks, sichere Updates und Backups.
Nathan Base -
Selfhosting & WebDocker belegt zu viel Speicher: sicher aufräumen
Docker füllt die Platte? So findest Du mit docker system df die Ursache, räumst Images und Build-Cache sicher auf und begrenzt wachsende Container-Logs.
Nathan Base -
Raspberry Pi & Linuxjournalctl: Fehler unter Linux in den Logs finden
Mit journalctl findest Du heraus, warum ein Dienst streikt oder der Pi neu startet: nach Dienst, Zeit und Priorität filtern, Journal dauerhaft speichern.
Nathan Base -
Selfhosting & WebUSV am Homeserver: bei Stromausfall sauber herunterfahren
So fährt Dein Homeserver oder Raspberry Pi bei Stromausfall automatisch herunter: passende USV wählen, NUT unter Debian einrichten und sicher testen.
Nathan Base -
Selfhosting & WebNextcloud mit Docker Compose installieren und absichern
Nextcloud mit Docker Compose, MariaDB, Redis und Caddy selbst hosten: mit HTTPS, Cron, Kalender und Kontakten fürs iPhone und Hilfe bei den Warnungen.
Nathan Base -
Selfhosting & WebUptime Kuma einrichten: Websites und Dienste überwachen
Uptime Kuma 2 mit Docker Compose installieren, Websites und SSL-Zertifikate überwachen, per ntfy oder Telegram alarmieren und eine Statusseite anlegen.
Nathan Base