Docker-Compose-Fehler mit ChatGPT systematisch analysieren

docker compose up -d – und wenige Sekunden später steht ein Container auf Restarting, ein anderer auf Exited (1) und die Anwendung behauptet, dass sie ihre Datenbank nicht erreichen kann.

Also kopiert man die letzte Fehlermeldung in ChatGPT.

Das funktioniert manchmal. Häufig beginnt dann aber das große Rätselraten.

Der Grund ist einfach: Eine einzelne Fehlermeldung zeigt meistens nur das Symptom, nicht die eigentliche Ursache.

Bei Docker Compose können Fehler aus vielen unterschiedlichen Ebenen kommen: aus der Compose-Datei, aus Umgebungsvariablen, einem Container-Image, einem falschen Mount, einem Netzwerk, fehlenden Dateirechten oder einer Anwendung innerhalb des Containers.

ChatGPT kann bei der Analyse sehr hilfreich sein – wenn wir dem Modell die richtigen Informationen geben.

In dieser Anleitung zeige ich einen reproduzierbaren Workflow, mit dem sich Docker-Compose-Fehler mit ChatGPT systematisch analysieren lassen. Einen allgemeinen Einstieg in die Docker-Fehleranalyse mit ChatGPT bietet der Artikel Docker-Fehler mit ChatGPT analysieren und beheben: Praxis-Anleitung 2026 (Zum Artikel). Dieser Beitrag vertieft gezielt die Besonderheiten von Docker Compose mit mehreren zusammenspielenden Services.

Warum Docker-Compose-Fehler oft schwer zu finden sind

Eine Compose-Anwendung besteht selten nur aus einem Container.

Typische Stacks enthalten beispielsweise:

Reverse Proxy
│
▼
Web-Anwendung
│
├── Datenbank
├── Redis
└── Worker

Wenn die Web-Anwendung nicht startet, muss die Anwendung selbst deshalb nicht zwingend defekt sein.

Vielleicht läuft die Datenbank noch nicht.

Vielleicht verwendet die Anwendung als Datenbankserver localhost, obwohl sie eigentlich den Compose-Servicenamen verwenden müsste.

Oder eine Variable aus der .env-Datei wurde anders aufgelöst als erwartet.

Genau deshalb ist die Reihenfolge der Analyse entscheidend. Läuft vor dem Compose-Stack zusätzlich ein Reverse Proxy wie HAProxy, lohnt sich bei Verbindungsfehlern zusätzlich ein Blick in den Artikel HAProxy-Fehler mit ChatGPT analysieren: Logs, Backends und Timeouts (Zum Artikel).

Schritt 1: Docker- und Compose-Version feststellen

Bevor wir die Anwendung analysieren, sollten wir wissen, womit sie überhaupt gestartet wird.

docker version
docker compose version

Das ist insbesondere bei älteren Tutorials wichtig.

Aktuelle Docker-Compose-Installationen verwenden docker compose statt des alten Befehls docker-compose.

Auch Einträge wie version: "3.8" sind in aktuellen Compose-Dateien nicht mehr notwendig. Docker bezeichnet die Top-Level-Eigenschaft version inzwischen als veraltet; Compose verwendet zur Validierung die aktuelle Compose Specification.

Eine moderne Datei beginnt deshalb beispielsweise direkt mit:

services:
  web:
    image: nginx:latest

Eine Warnung bezüglich version bedeutet also nicht zwangsläufig, dass der Stack deshalb nicht funktioniert.

Schritt 2: Die Compose-Datei zuerst validieren

Bevor Logs analysiert werden, sollte geprüft werden, ob Docker die Konfiguration überhaupt so interpretiert, wie wir denken.

Dafür ist einer der wichtigsten Befehle:

docker compose config

Docker führt dabei unter anderem die verwendeten Compose-Dateien zusammen, löst Variablen auf und zeigt das daraus resultierende Compose-Modell an.

Wer zunächst nur wissen möchte, ob die Konfiguration gültig ist, kann verwenden:

docker compose config -q

Interessant sind außerdem:

docker compose config --services
docker compose config --networks
docker compose config --volumes

Damit lassen sich beispielsweise Tippfehler bei Services oder Netzwerkdefinitionen schneller erkennen.

Für Probleme mit Variablen ist auch Folgendes interessant:

docker compose config --environment

Wichtig: Die Ausgabe kann vertrauliche Werte enthalten. Passwörter, Tokens, API-Keys und andere Secrets sollten niemals ungefiltert an ChatGPT oder andere externe Systeme übergeben werden.

Aus:

DB_PASSWORD=SuperSecret123!
API_TOKEN=abcdef123456789

sollte beispielsweise werden:

DB_PASSWORD=<REDACTED>
API_TOKEN=<REDACTED>

Der Variablenname ist für die Fehlersuche meistens wichtiger als dessen tatsächlicher geheimer Wert.

Schritt 3: Änderungen mit Dry-Run prüfen

Bei einem produktiven System sollte man nicht jeden vermeintlichen Lösungsvorschlag sofort ausprobieren.

Aktuelle Compose-Versionen unterstützen einen Dry-Run-Modus:

docker compose --dry-run up --build -d

Damit lässt sich nachvollziehen, welche Aktionen Compose ausführen würde, ohne die Änderungen tatsächlich auf den Stack anzuwenden. Docker dokumentiert den Dry-Run inzwischen direkt als globale Compose-Option.

Das ist besonders praktisch, wenn ChatGPT beispielsweise Änderungen an Images, Netzwerken oder Containerdefinitionen vorgeschlagen hat.

Schritt 4: Den tatsächlichen Containerstatus prüfen

Jetzt kommt die erste Momentaufnahme des Systems:

docker compose ps --all

Das --all ist wichtig.

Ein normales docker compose ps zeigt standardmäßig nur laufende Container. Mit --all erscheinen auch bereits beendete Container.

Beispiel:

NAME             SERVICE   STATUS
myapp-web-1      web       Up 2 minutes
myapp-db-1       db        Up 2 minutes (healthy)
myapp-worker-1   worker    Exited (1)
myapp-redis-1    redis     Restarting

Jetzt wissen wir bereits wesentlich mehr.

Der Fehler betrifft offenbar nicht den gesamten Stack.

web läuft. db läuft und ist healthy. worker ist mit Exit Code 1 beendet worden. redis steckt in einer Restart-Schleife.

Damit kann die Analyse gezielt beginnen.

Schritt 5: Logs nicht wahllos, sondern gezielt auslesen

Einer der häufigsten Fehler bei der KI-gestützten Fehlersuche besteht darin, mehrere Tausend Logzeilen ungefiltert in ChatGPT zu kopieren.

Besser ist:

docker compose logs --tail=100 worker

Oder mit Zeitstempeln:

docker compose logs --timestamps --tail=200 worker

Für eine Live-Analyse:

docker compose logs -f worker

Compose unterstützt unter anderem Filter nach Zeit, die Begrenzung der letzten Zeilen und das kontinuierliche Folgen der Logs.

Wenn der Fehler gerade aufgetreten ist, kann beispielsweise auch sinnvoll sein:

docker compose logs --since=10m worker

Das reduziert den Datenmüll erheblich. ChatGPT bekommt dadurch genau den Bereich, in dem der Fehler passiert ist. Wie du dieses Prinzip der gezielten, gefilterten Log-Auswertung auch außerhalb von Docker auf Linux-Systemen einsetzt, zeigt der Artikel Linux-Logs mit ChatGPT analysieren: syslog, auth.log und journalctl (Zum Artikel).

Schritt 6: Exit Code und Containerstatus analysieren

Ein Container mit Exited (1) liefert bereits einen wichtigen Hinweis.

Aber der Exit Code allein reicht oft nicht.

Deshalb folgt:

docker inspect CONTAINERNAME

docker inspect liefert detaillierte Informationen über Docker-Objekte und eignet sich beispielsweise zur Untersuchung von Status, Mounts, Netzwerken und Containerkonfigurationen.

Besonders interessant sind Felder wie:

State.Status
State.ExitCode
State.Error
State.OOMKilled
State.Health
RestartCount
Mounts
NetworkSettings

Die Anzahl der Neustarts lässt sich beispielsweise gezielt auslesen:

docker inspect -f '{{ .RestartCount }}' CONTAINERNAME

Bei ständig neu startenden Containern erkennt man dadurch schnell eine Restart-Schleife. Docker stellt RestartCount über docker inspect bereit.

Schritt 7: Docker-Compose-Netzwerke prüfen

Netzwerkprobleme gehören zu den häufigsten Compose-Fehlern.

Ein klassisches Beispiel:

DB_HOST=localhost

Die Anwendung läuft jedoch im Container web, während PostgreSQL im Container db läuft.

Innerhalb des web-Containers bedeutet localhost nicht der Docker-Host und auch nicht der Datenbankcontainer. Es bedeutet: dieser Container selbst.

Bei einem normalen Compose-Netzwerk können Services sich standardmäßig über ihren Servicenamen erreichen. Docker erstellt für eine Compose-Anwendung normalerweise ein gemeinsames Default-Netzwerk und stellt darin die Namensauflösung zwischen den Services bereit.

Statt DB_HOST=localhost müsste deshalb typischerweise stehen: DB_HOST=db, wenn der Service so definiert wurde:

services:
  web:
    image: myapp
  db:
    image: postgres

Die Namensauflösung lässt sich direkt aus einem Container testen:

docker compose exec web getent hosts db

Falls das verwendete Image entsprechende Werkzeuge enthält, kann anschließend auch der Port getestet werden. Beispielsweise:

docker compose exec web nc -zv db 5432

oder:

docker compose exec web curl http://api:8080

Damit lässt sich unterscheiden zwischen „DNS funktioniert nicht" und „DNS funktioniert, aber der Dienst antwortet nicht". Das ist für ChatGPT ein wesentlicher Unterschied.

Schritt 8: depends_on bedeutet nicht automatisch „bereit"

Ein weiterer Klassiker:

depends_on:
  - db

Viele Administratoren erwarten dadurch: Die Anwendung startet erst, wenn die Datenbank vollständig bereit ist.

Das stimmt so nicht.

Docker weist ausdrücklich darauf hin, dass Compose standardmäßig darauf wartet, dass der abhängige Container gestartet wurde – nicht darauf, dass die darin laufende Anwendung tatsächlich betriebsbereit ist.

Eine Datenbank kann also bereits als Container laufen und trotzdem noch keine Verbindungen akzeptieren.

Eine robustere Konfiguration arbeitet deshalb mit einem Healthcheck. Beispiel:

services:
  db:
    image: postgres
    environment:
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: mydb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myuser -d mydb"]
      interval: 10s
      timeout: 5s
      retries: 5
  web:
    image: myapp
    depends_on:
      db:
        condition: service_healthy

Compose kann mit condition: service_healthy darauf warten, dass der Healthcheck einer Abhängigkeit erfolgreich ist.

Wenn eine Anwendung unmittelbar nach dem Start Fehler wie Connection refused produziert, wenige Sekunden später aber problemlos funktioniert, sollte genau dieser Bereich untersucht werden.

Schritt 9: Volumes und Berechtigungen kontrollieren

Ein Container startet lokal problemlos, auf dem Linux-Server jedoch nicht?

Dann sollte ein Blick auf die Volumes folgen. Beispiel:

volumes:
  - ./config:/app/config
  - ./data:/app/data

Typische Ursachen sind falsche Pfade, fehlende Verzeichnisse, falsche Eigentümer oder unpassende Dateirechte.

Auf dem Host helfen:

ls -la
ls -ln

Innerhalb des Containers:

docker compose exec web id
docker compose exec web ls -ln /app/data

Ein häufiger Fehler sieht dann ungefähr so aus:

Host:              1000:1000
Containerprozess:  1001:1001

Wenn die Anwendung Schreibzugriff benötigt, kann genau dieser Unterschied entscheidend sein.

Blind chmod -R 777 auszuführen, ist dabei keine gute Fehlerbehebung.

Besser ist zunächst festzustellen, welcher Benutzer auf welches Verzeichnis mit welchen Rechten zugreifen muss.

Schritt 10: Umgebungsvariablen überprüfen

Eine Anwendung kann korrekt gebaut sein und trotzdem mit völlig falscher Konfiguration starten.

Beispiel:

environment:
  DB_HOST: ${DB_HOST}
  DB_USER: ${DB_USER}
  DB_PASSWORD: ${DB_PASSWORD}

In der .env steht möglicherweise DB_HOST=localhost, oder eine benötigte Variable fehlt komplett.

Deshalb ist die Ausgabe von docker compose config so wertvoll.

Sie zeigt nicht nur die YAML-Datei, die wir geschrieben haben, sondern das daraus aufgelöste Compose-Modell.

Gerade bei mehreren Compose-Dateien wie:

docker compose \
  -f compose.yaml \
  -f compose.production.yaml \
  up -d

kann das einen erheblichen Unterschied machen. Docker unterstützt bewusst das Überlagern mehrerer Compose-Dateien, beispielsweise für unterschiedliche Produktionskonfigurationen.

Schritt 11: Ressourcen des Hosts nicht vergessen

Nicht jeder Docker-Fehler steckt in Docker.

Ein Container kann beispielsweise durch Speichermangel beendet werden.

Deshalb gehören bei schwer erklärbaren Fehlern auch klassische Linux-Kommandos zur Diagnose:

free -h
df -h
df -i
docker stats

Zusätzlich sollte bei verdächtigen Containern wieder der State untersucht werden:

docker inspect CONTAINERNAME

Besonders interessant ist OOMKilled. Ist dieser Wert true, muss die Analyse eher in Richtung Arbeitsspeicher und Ressourcenlimits gehen als in Richtung Netzwerk oder YAML.

Welche Informationen sollte ich ChatGPT geben?

Der Unterschied zwischen einer schlechten und einer guten ChatGPT-Analyse liegt häufig im Prompt.

Schlecht wäre: „Mein Docker Container startet nicht. Warum?"

ChatGPT kann darauf nur Vermutungen liefern.

Wesentlich besser ist ein strukturierter Diagnose-Prompt. Weitere kopierfertige Prompt-Vorlagen für den IT-Alltag liefert der Artikel 10 ChatGPT-Prompts für IT-Support und Helpdesk (Zum Artikel).

Prompt-Vorlage für Docker-Compose-Fehler

Du bist ein Linux- und Docker-Administrator.

Analysiere den folgenden Docker-Compose-Fehler systematisch.

Bitte ändere nicht sofort meine Compose-Datei, sondern:

1. Trenne Symptome von möglichen Ursachen.
2. Nenne zuerst die wahrscheinlichsten Ursachen.
3. Erkläre, welche vorhandenen Daten deine Vermutung stützen.
4. Nenne die nächsten Diagnosebefehle.
5. Warte mit größeren Änderungen, bis die Ursache eingegrenzt ist.
6. Weise darauf hin, wenn Informationen fehlen.
7. Gib bei Änderungen exakt an, welche Zeilen geändert werden sollten.
8. Vermeide destruktive Docker-Befehle, solange sie nicht notwendig sind.

Docker-Version:
[Ausgabe einfügen]

Docker-Compose-Version:
[Ausgabe einfügen]

docker compose ps --all:
[Ausgabe einfügen]

docker compose config:
[relevante Ausgabe einfügen]

Logs des betroffenen Services:
[Ausgabe einfügen]

docker inspect / relevante State-Daten:
[Ausgabe einfügen]

Fehlerbild:
[Beschreiben, was funktioniert und was nicht]

Änderungen unmittelbar vor dem Fehler:
[falls vorhanden]

WICHTIG:
Passwörter, Tokens und Secrets wurden aus den Ausgaben entfernt.

Mit diesem Prompt bekommt ChatGPT nicht nur einen Fehlertext, sondern einen kleinen Diagnosefall. Und genau das verbessert die Qualität der Analyse erheblich.

Typische Docker-Compose-Fehler und der nächste sinnvolle Test

Diese Tabelle ist auch eine gute Orientierung dafür, welche Informationen ChatGPT als Nächstes benötigt.

Warum „docker compose down -v" keine Standardlösung ist

Im Internet findet man bei Compose-Problemen erstaunlich häufig Befehle wie:

docker compose down -v

Das kann jedoch Volumes entfernen.

Bei einer Datenbank könnte damit genau das gelöscht werden, was man eigentlich erhalten möchte.

Ähnlich problematisch sind reflexartige Befehle wie:

docker system prune -a

Eine gute KI-gestützte Fehleranalyse sollte daher nicht mit Bereinigungsaktionen beginnen.

Die bessere Reihenfolge lautet:

Beobachten
→ Zustand erfassen
→ Ursache eingrenzen
→ Hypothese testen
→ Änderung durchführen
→ Ergebnis überprüfen

Erst danach sollte über Aufräum- oder Neuaufbauaktionen nachgedacht werden.

ChatGPT sollte Hypothesen liefern – keine Befehle zum blinden Kopieren

Der größte Nutzen von ChatGPT liegt bei Docker-Problemen nicht darin, dass die KI irgendeinen Linux-Befehl kennt.

Das eigentliche Potenzial liegt darin, Informationen miteinander zu verbinden.

Zum Beispiel: Containerstatus Restarting, Log connection refused, DB_HOST: localhost, Compose-Service heißt db.

Daraus kann relativ schnell die Hypothese entstehen: Die Anwendung versucht wahrscheinlich, die Datenbank im eigenen Container zu erreichen, anstatt den Compose-Service db anzusprechen.

Diese Hypothese lässt sich anschließend überprüfen.

Genau so sollte KI bei administrativen Aufgaben eingesetzt werden: Analyse unterstützen, Hypothesen bilden und Tests vorschlagen – aber nicht unkontrolliert produktive Systeme verändern.

Ein sinnvoller Docker-Compose-Debugging-Workflow

Für die Praxis lässt sich die gesamte Vorgehensweise auf einen kompakten Ablauf reduzieren:

docker version
↓
docker compose version
↓
docker compose config -q
↓
docker compose config
↓
docker compose --dry-run up -d
↓
docker compose ps --all
↓
docker compose logs --timestamps --tail=200 SERVICE
↓
docker inspect CONTAINER
↓
docker stats

Danach werden je nach Fehlerbild Netzwerk, Volumes, Berechtigungen, Variablen oder Healthchecks untersucht.

Wer ChatGPT erst nach diesen Schritten hinzuzieht, bekommt in der Regel wesentlich gezieltere Antworten als mit einem einzelnen Screenshot oder einer isolierten Fehlermeldung.

Was sollte man niemals ungefiltert an ChatGPT übertragen?

Docker-Konfigurationen enthalten regelmäßig sensible Informationen.

Dazu können gehören: Datenbankpasswörter, API-Keys, OAuth-Tokens, JWT-Secrets, Private Registry Credentials, interne Hostnamen, interne IP-Adressen, Kundendaten, SSH-Keys, Zertifikate und Private Keys.

Vor dem Übertragen von Logs oder Konfigurationen sollten diese Informationen entfernt oder anonymisiert werden. Wie du Zugangsdaten und API-Keys bei KI-gestützten Workflows grundsätzlich schützt, erklärt der Artikel Secrets und API-Keys bei KI-Agenten schützen (Zum Artikel).

Aus:

mysql://admin:P4ssw0rd@db-production.internal:3306/customerdb

kann beispielsweise werden:

mysql://<USER>:<PASSWORD>@<DB_HOST>:3306/<DATABASE>

Für die technische Analyse bleibt die Struktur erhalten – die vertraulichen Informationen verschwinden.

Fazit: Docker-Compose-Fehler mit ChatGPT richtig analysieren

ChatGPT kann bei Docker Compose ein hervorragender Troubleshooting-Assistent sein.

Der entscheidende Punkt ist allerdings die Qualität der Diagnoseinformationen.

Statt nur „Mein Container funktioniert nicht." sollten wir zuerst systematisch feststellen: Welche Konfiguration verwendet Compose wirklich? Welche Container laufen? Welche Container sind beendet? Welchen Exit Code gibt es? Was steht unmittelbar vor dem Fehler im Log? Kann der Container seine Abhängigkeiten erreichen? Sind Volumes und Berechtigungen korrekt? Ist eine Abhängigkeit nur gestartet oder tatsächlich healthy?

Mit Werkzeugen wie docker compose config, docker compose ps --all, docker compose logs, docker inspect und dem Compose-Dry-Run entsteht aus einer unspezifischen Fehlermeldung ein nachvollziehbarer Diagnosefall. Die aktuellen Docker-Werkzeuge stellen genau diese Informationen bereit.

Und genau dann wird ChatGPT beim Troubleshooting wirklich nützlich.

Nicht die KI sollte raten, was mit deinem Docker-Stack passiert. Gib ihr die Daten, mit denen sie die Ursache eingrenzen kann.

Häufige Fragen

Kann ChatGPT eine docker-compose.yml auf Fehler prüfen?

Ja. ChatGPT kann YAML-Strukturen, Compose-Konfigurationen und typische Fehlkonfigurationen analysieren. Zusätzlich sollte die Datei jedoch immer mit docker compose config beziehungsweise docker compose config -q durch Compose selbst validiert werden.

Was bedeutet Exited (1) bei Docker Compose?

Exited (1) bedeutet zunächst nur, dass der Hauptprozess des Containers mit Exit Code 1 beendet wurde. Die eigentliche Ursache findet sich normalerweise in den Logs der Anwendung oder weiteren Informationen aus docker inspect.

Wie sehe ich auch beendete Docker-Compose-Container?

Mit docker compose ps --all. Ohne --all zeigt docker compose ps standardmäßig nur laufende Container an.

Warum erreicht mein Container eine andere Anwendung nicht über localhost?

Weil localhost innerhalb eines Containers normalerweise auf diesen Container selbst verweist. Services innerhalb desselben Compose-Netzwerks können sich normalerweise über ihren Compose-Servicenamen erreichen.

Reicht depends_on aus, damit meine Datenbank vor der Anwendung startet?

depends_on kann die Startreihenfolge steuern, garantiert aber nicht automatisch, dass die Anwendung innerhalb des abhängigen Containers bereits einsatzbereit ist. Dafür können Healthchecks zusammen mit condition: service_healthy verwendet werden.

Welche Docker-Logs sollte ich ChatGPT geben?

Am sinnvollsten sind die Logs des betroffenen Services rund um den Fehlerzeitpunkt, beispielsweise: docker compose logs --timestamps --tail=200 SERVICE. Bei Bedarf kann der Zeitraum zusätzlich über --since eingeschränkt werden.

Quellenbasis

Technische Details und Befehle wurden anhand der aktuellen offiziellen Docker-Dokumentation zur Compose Specification, zu docker compose config, docker compose ps, docker compose logs, Networking, Startup-Reihenfolge, Healthchecks, Dry-Run und docker inspect geprüft.