Docker Compose Fehlerbehebung: 5 häufige Fehler und schnelle Lösungen

Freitag, 15:30 Uhr – bis zur Code-Abgabe sind noch zwei Stunden.

In der Konsole blinkt die rote Fehlermeldung: Error starting userland proxy: Bind for 0.0.0.0:8080 failed: port is already allocated. Gestern lief alles noch einwandfrei – heute startet nichts mehr.

Strg+C, nochmal. Gleicher Fehler. Google-Suche nach „docker compose port already allocated”, fünf oder sechs Stack-Overflow-Threads geöffnet, jede Lösung ausprobiert: Docker neu starten, Container löschen, Port ändern … die Fehlermeldung bleibt unverändert.

Docker Compose Fehlermeldungen sind oft dutzende Zeilen lang – die eine relevante Zeile steckt in Zeile 23, und Sie verlieren schon in Zeile 1 die Nerven. Dieser Artikel fasst meine Erfahrungen aus zwei Jahren zusammen: 5 häufige Docker Compose Fehlerklassen, jeweils nach dem Muster „Fehlermerkmale → Ursache → Lösung”. Sie werden sehen: 90 % der Fehler sind in 5 Minuten lösbar – wenn Sie wissen, wo Sie anfangen.

Grundlagen – 3 Kernwerkzeuge beherrschen

Bevor wir konkrete Fehler angehen: Die drei Befehle, die ich täglich dutzende Male nutze.

Werkzeug 1: docker-compose ps – Status schnell prüfen

Dieser Befehl zeigt, welche Container laufen und welche ausgefallen sind.

docker-compose ps

Spalte State beachten:

• Up – normaler Betrieb, Entwarnung
• Exit – Start fehlgeschlagen oder Absturz während des Betriebs
• Restarting – ständiger Neustart, Startbefehl hat vermutlich ein Problem

Wenn ein Service Exit 1 zeigt, weiß ich: Zeit, die Logs zu prüfen.

Werkzeug 2: docker-compose logs – Logs durchsuchen

Das Herzstück der Fehlersuche.

# Logs aller Services
docker-compose logs

# Nur nginx-Logs
docker-compose logs nginx

# Echtzeit-Verfolgung (ähnlich tail -f)
docker-compose logs -f

# Nur die letzten 100 Zeilen
docker-compose logs --tail 100 nginx

Ehrlich gesagt sind Docker-Logs manchmal unübersichtlich – aber in 90 % der Fälle steht die eigentliche Fehlermeldung in den letzten Zeilen. Nach oben scrollen und nach ERROR, failed, cannot suchen.

Werkzeug 3: docker inspect – Tiefenanalyse (nur bei Bedarf)

Wenn die ersten beiden Befehle nicht reichen.

# Vollständige Container-Konfiguration anzeigen
docker inspect container-name

# Nur Status
docker inspect --format='{{.State.Status}}' container-name

# IP-Adresse
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container-name

Allgemeiner Troubleshooting-Workflow (merken)

Bei Problemen ruhig bleiben und so vorgehen:

1. docker-compose ps – welcher Service ist ausgefallen?
2. docker-compose logs [service-name] – konkrete Fehlermeldung finden
3. docker inspect – Tiefenanalyse (meist nicht nötig)

Werkzeuge bereit? Jetzt zu den 5 häufigsten Fehlern.

Portkonflikt – „port is already allocated”

Diesen Fehler sehe ich ständig. Typische Meldung:

Error starting userland proxy: Bind for 0.0.0.0:8080 failed: port is already allocated

Oder:

ERROR: for nginx  Cannot start service nginx: driver failed programming external connectivity on endpoint xxx: Bind for 0.0.0.0:80 failed: port is already allocated

Warum passiert das?

Meist eine von drei Ursachen:

1. Nach docker-compose up wurde Strg+C gedrückt, aber kein docker-compose down ausgeführt – Container laufen noch im Hintergrund
2. Port in docker-compose.yml geändert, aber alte Container nicht vollständig entfernt
3. Ein anderes Programm auf dem Rechner belegt den Port (lokaler Nginx, MySQL usw.)

Lösungen (von einfach zu komplex, der Reihe nach testen)

Lösung 1: Aufräumen und neu starten (90 % wirksam)

docker-compose down
docker-compose up -d

Für mich die zuverlässigste Methode. down stoppt alle Container und entfernt sie, behält aber Volume-Daten.

Lösung 2: Container finden, der den Port blockiert

Wenn Lösung 1 nicht hilft, gibt es vermutlich „Geister-Container” – nicht zum aktuellen Projekt gehörend, aber den Port blockierend.

# Alle Container auflisten (auch gestoppte)
docker ps -a | grep 8080

# Nach container_id stoppen und entfernen
docker stop <container_id>
docker rm <container_id>

Lösung 3: docker-proxy-Prozesse prüfen

Manchmal sind Container weg, aber docker-proxy-Prozesse hängen noch.

# docker-proxy-Prozesse anzeigen
ps aux | grep docker-proxy | grep 8080

# Bei Restprozessen Docker-Dienst neu starten
sudo systemctl restart docker  # Linux
# Auf dem Mac: Docker Desktop → Restart

Lösung 4: Host-Portbelegung prüfen

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

Vielleicht blockiert ein lokales Programm den Port.

# Linux/Mac
lsof -i :8080
netstat -tlnp | grep 8080

# Windows
netstat -ano | findstr 8080

Ist es ein anderes Programm: entweder beenden oder Port in docker-compose.yml ändern.

Lösung 5: Port-Konfiguration ändern (wenn nichts anderes hilft)

docker-compose.yml bearbeiten:

services:
  web:
    ports:
      - "8081:80"  # 8080 durch 8081 ersetzen

Mein Tipp

Gewohnheit: Container mit docker-compose down stoppen, nicht nur Strg+C. Früher habe ich oft Strg+C genutzt – regelmäßig Portkonflikte. Seit dem Wechsel ist dieser Fehler praktisch verschwunden.

In der Entwicklung lieber Nicht-Standard-Ports nutzen. Statt 80 oder 3306 eher 8080 oder 3307 – weniger Konflikte mit Systemdiensten.

Netzwerkprobleme – „network declared as external but could not be found”

Typische Meldung:

ERROR: Network my_network declared as external, but could not be found. Please create the network manually using `docker network create my_network` and try again.

Warum tritt dieser Fehler auf?

Eine häufige Falle bei Docker Compose: Ist ein Netzwerk in docker-compose.yml als external: true markiert, geht Docker davon aus, dass es bereits existiert – und erstellt es nicht automatisch. Findet es das Netzwerk nicht, kommt der Fehler.

Typische Szenarien:

1. Fremde Konfiguration kopiert, die ein externes Netzwerk nutzt – lokal aber nicht vorhanden
2. Docker neu gestartet, Netzwerkkonfiguration teilweise verloren
3. Netzwerkname falsch geschrieben (Groß-/Kleinschreibung beachten!)

Lösungen

Lösung 1: Vorhandene Netzwerke auflisten, Namen prüfen

docker network ls

Vielleicht heißt das Netzwerk tatsächlich myproject_app_network, nicht app_network. Docker Compose setzt oft ein Projektprefix vor den Namen.

Lösung 2: Fehlendes Netzwerk manuell erstellen

docker network create my_network

Lösung 3: Konfigurationsdatei korrigieren

Drei Varianten – eine wählen:

# Variante A: external entfernen, Compose erstellt automatisch
networks:
  app_network:
    driver: bridge

# Variante B: name-Feld für expliziten Netzwerknamen
networks:
  app_network:
    external: true
    name: my_actual_network_name

# Variante C: Netzwerk manuell erstellen, dann external referenzieren

Ich bevorzuge Variante A. Nur wenn Netzwerke zwischen mehreren Compose-Projekten geteilt werden sollen, lohnt sich external.

Lösung 4: Aufräumen und neu aufbauen (nach Docker-Neustart)

docker-compose down
docker network prune  # Ungenutzte Netzwerke bereinigen
docker-compose up -d

Fallen vermeiden

• Klar trennen: welche Netzwerke external sein sollen (projektübergreifend) und welche Compose verwaltet (ein Projekt)
• name-Feld nutzen, um automatische Prefixes zu vermeiden
• In der Team-README dokumentieren, welche externen Netzwerke vorab erstellt werden müssen

Build fehlgeschlagen – „service failed to build”

Diese Meldung erscheint:

ERROR: Service 'app' failed to build: Build failed

Wichtiger Tipp: Logs nach oben scrollen

„service failed to build” ist nur die Zusammenfassung – das eigentliche Problem steht weiter oben. 50–100 Zeilen zurückscrollen und nach ERROR, failed, cannot, not found, permission denied suchen.

Beim ersten Mal habe ich nur die letzte Zeile angestarrt. Später lernte ich: Die echte Meldung steckt oft bei „npm install failed” oder „file not found” – versteckt im Output.

Häufige Unterfehler

Typ 1: Datei nicht gefunden

COPY failed: stat /var/lib/docker/tmp/.../package.json: no such file or directory

Ursachen:

• Falscher build context-Pfad
• .dockerignore schließt benötigte Dateien aus

Lösung:

# context in docker-compose.yml prüfen
services:
  app:
    build:
      context: ./my-app  # Pfad korrekt?
      dockerfile: Dockerfile

# .dockerignore temporär umbenennen zum Testen
mv .dockerignore .dockerignore.bak
docker-compose build app

Typ 2: Abhängigkeitsinstallation fehlgeschlagen

npm ERR! 404 Not Found - GET https://registry.npmjs.org/xxx

Oder:

E: Unable to locate package xxx

Ursachen: falscher Paketname, nicht existierende Version, Netzwerkproblem

Lösung:

# Spiegel-Registry im Dockerfile (Beispiel China)
RUN npm config set registry https://registry.npmmirror.com
RUN npm install

# Oder apt-Quellen wechseln
RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list
RUN apt-get update && apt-get install -y xxx

Typ 3: Speichermangel

The command '/bin/sh -c npm install' returned a non-zero code: 137
signal: killed

Exit-Code 137 bedeutet meist: nicht genug Speicher.

Lösung:

• Docker Desktop → Settings → Resources → Memory, mindestens 4 GB
• Oder im Dockerfile weniger Parallelität: RUN npm install --max_old_space_size=4096

Typ 4: Dockerfile-Syntaxfehler

Falscher Befehlsname oder falscher COPY-Pfad.

Lösung: isoliert testen:

cd build-directory
docker build -t test-build .

Klarere Fehlermeldungen als bei docker-compose build.

Debug-Methoden

Neu bauen ohne Cache:

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

docker-compose build --no-cache service_name

Manchmal ist ein fehlerhafter Cache-Layer schuld – Cache leeren hilft.

Build-Kontext prüfen:

docker-compose config

Zeigt die vollständig aufgelöste Compose-Konfiguration – hilft bei Pfadproblemen.

Meine Erfahrung

• Eine funktionierende Build-Version als Baseline behalten
• Dockerfile schrittweise ändern – nicht alles auf einmal
• Bei langsamem Build: Multi-Stage-Build oder Reihenfolge optimieren, selten geänderte Schritte nach vorne für besseres Caching

Container startet und beendet sich – „exited with code X”

Heimtückischer: Image baut erfolgreich, Container startet – und beendet sich sofort.

docker-compose ps zeigt dann:

Name              State
app_web_1         Exit 1
app_db_1          Up

Exit-Codes (merken)

• Exit 0: Normaler Exit – für Container aber oft problematisch (Befehl ist fertig)
• Exit 1: Anwendungsfehler (am häufigsten)
• Exit 137: Speichermangel (OOM) oder kill
• Exit 139: Segmentation Fault
• Exit 143: SIGTERM empfangen (meist manueller Stop)

Troubleshooting-Schritte

Schritt 1: Logs prüfen

docker-compose logs service_name

In 90 % der Fälle steht die Ursache in den Logs.

Schritt 2: Manuell in den Container gehen

Wenn Logs nicht helfen, docker-compose.yml anpassen, damit der Container läuft:

services:
  app:
    command: sleep infinity  # Container am Leben halten

Dann:

docker-compose up -d
docker-compose exec app sh  # Container betreten
# Ursprünglichen Startbefehl manuell ausführen und Fehler beobachten

Gezielte Lösungen

Exit 0 – Befehl beendet, Container folgt

Wenn command: echo "Hello" gesetzt ist, ist nach der Ausgabe nichts mehr zu tun – Container beendet sich.

Lösung: Daemon oder blockierenden Befehl verwenden:

# Falsch
command: echo "Started"

# Richtig
command: npm start  # dauerhaft laufender Prozess

Exit 1 – Anwendungsfehler

Logs prüfen. Häufige Ursachen:

• Falscher Konfigurationsdatei-Pfad
• Fehlende Umgebungsvariablen
• Datenbankverbindung fehlgeschlagen (DB noch nicht bereit)
• Berechtigungsproblem

Exit 137 – Speichermangel

Container-Speicherlimit setzen:

services:
  app:
    mem_limit: 2g
    memswap_limit: 2g

Oder Gesamtspeicher in Docker Desktop erhöhen.

Abhängiger Dienst noch nicht bereit

Klassische Falle: App-Container startet, DB initialisiert noch – App bricht ab.

Lösung: depends_on mit healthcheck:

services:
  app:
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

App wartet, bis die DB wirklich bereit ist.

Meine Fallen

Ein Container beendete sich ständig mit Exit 1 – Log: „Config file not found”. Ursache: relativer Pfad zur Konfiguration, Arbeitsverzeichnis im Container anders als erwartet. Absoluter Pfad löste es.

Einmal falsches DB-Passwort – App startete und stürzte ab. Die Meldung stand klar in den Logs – 20 Minuten verschwendet, weil ich nicht genau hingeschaut habe.

Berechtigungsprobleme – „permission denied”

Besonders häufig bei Volume-Mounts:

Error: EACCES: permission denied, open '/app/data/config.json'

Oder „Permission denied” in den Logs, ohne klare Dateiangabe.

Warum Berechtigungsprobleme?

UID/GID im Container stimmen nicht mit dem Dateibesitzer auf dem Host überein. Beispiel:

• Host-Dateien gehören Ihnen (UID 1000)
• App im Container läuft als www-data (UID 33)
• www-data darf nicht lesen/schreiben → Fehler

Lösungen

Lösung 1: user mit UID/GID angeben (empfohlen)

Container unter Ihrer Benutzeridentität laufen lassen:

services:
  app:
    user: "${UID}:${GID}"
    volumes:
      - ./data:/app/data

Start:

UID=$(id -u) GID=$(id -g) docker-compose up

Oder in .env:

# .env
UID=1000
GID=1000

Lösung 2: Berechtigungen auf dem Host ändern

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Direkt:

chmod -R 777 ./data  # Vorsicht – Sicherheitsrisiko
# Oder
chmod -R 755 ./data  # Sicherer
chown -R $(id -u):$(id -g) ./data

Lösung 3: SELinux (CentOS/RHEL) – Flag setzen

Bei CentOS/RHEL kann SELinux blockieren:

volumes:
  - ./data:/app/data:z  # Mehrere Container teilen
  # Oder
  - ./config:/app/config:Z  # Nur dieser Container

Unterschied z vs. Z: kleines z = geteilte Berechtigung, großes Z = exklusiv.

Lösung 4: Named Volume statt Bind Mount

Docker-verwaltete Volumes haben selten Berechtigungsprobleme:

services:
  app:
    volumes:
      - app_data:/app/data  # Named Volume

volumes:
  app_data:  # Docker verwaltet Berechtigungen

Nachteil: Dateien nicht direkt auf dem Host bearbeitbar – nur über den Container.

Lösung 5: Berechtigungen im Entrypoint-Skript anpassen

Für komplexe Szenarien:

# entrypoint.sh
#!/bin/sh
chown -R appuser:appuser /app/data
exec "$@"

COPY entrypoint.sh /
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["node", "app.js"]

Mein Tipp

• Produktion: Named Volumes – sicher, weniger Berechtigungsaufwand
• Entwicklung: Lösung 1 (user mit UID/GID) – Dateien direkt auf dem Host bearbeiten
• 777 vermeiden: Nur wenn Sie dem Code im Container voll vertrauen

Berechtigungen wirken kompliziert – sobald UID/GID-Zuordnung klar ist, wird es einfach.

Allgemeine Debug-Tipps – Zusammenfassung

Nach den konkreten Fehlern: systematisches Vorgehen.

Standard-Workflow (bewährt)

1. docker-compose ps           → Status, betroffenen Service finden
2. docker-compose logs <svc>  → Logs, Schlüsselfehler finden
3. docker-compose config       → Konfigurationssyntax validieren
4. docker inspect <container>  → Tiefenanalyse (bei Bedarf)
5. Isolierter Test             → Problematischen Service einzeln starten

Diese Gewohnheit spart Verwirrung.

Aufräum-Befehle (regelmäßig)

# Container stoppen und entfernen (Volumes behalten)
docker-compose down

# Inklusive Volumes (vorsichtig!)
docker-compose down -v

# Ungenutzte Ressourcen bereinigen
docker system prune

# Gründliche Bereinigung (alle Images)
docker system prune -a

# Neu bauen ohne Cache
docker-compose build --no-cache

# Docker-Speicherverbrauch anzeigen
docker system df

Freitags vor Feierabend laufe ich docker system prune – einmal 50 GB belegt, danach 10 GB.

Vorbeugung

Konfiguration validieren:

# Vor dem Start Konfiguration prüfen
docker-compose config

Prüft YAML-Syntax und findet Konfigurationsfehler.

Healthcheck:

services:
  web:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Mit Healthcheck erkennen Sie schneller, wenn ein Service läuft, aber nicht gesund ist.

Sinnvolle Restart-Policy:

services:
  app:
    restart: unless-stopped  # Empfohlen: immer neu starten, außer manuell gestoppt
    # restart: always        # Immer neu starten
    # restart: on-failure    # Nur bei Fehler

Umgebungsvariablen zentral verwalten:

# .env-Datei
DB_PASSWORD=your_password
API_KEY=your_key

# docker-compose.yml
services:
  app:
    environment:
      - DB_PASSWORD=${DB_PASSWORD}
      - API_KEY=${API_KEY}

Konfiguration ändern ohne YAML anzufassen – praktisch im Team.

Fazit

Zurück zum Anfang: Freitag 15:30, Deadline naht, Container startet nicht. Jetzt wissen Sie:

1. Ruhe bewahren
2. Fehlertyp erkennen (Port, Netzwerk, Build, Exit, Berechtigung)
3. Entsprechendes Kapitel – von einfach zu komplex
4. Im Zweifel: Logs lesen – die Antwort steht dort

Docker Compose Fehler sind nicht schlimm – fehlender systematischer Ansatz schon. Diese 5 Fehlerklassen und Lösungsmuster merken – beim nächsten Mal in 5 Minuten erledigt.

Letzter Tipp: Team-Wiki mit Fallen und Lösungen pflegen. Bei uns gibt es „Docker häufige Probleme” – neue Kollegen vermeiden damit etwa 80 % typischer Fehler.

Welche ungewöhnlichen Docker Compose Fehler haben Sie erlebt? Teilen Sie gern in den Kommentaren – vielleicht hilft es anderen.