March 8, 2026

“Connection refused” in Docker: Ursachen und schnelle Fixes

Der Fehler “Connection refused” in Docker tritt häufig auf, wenn Container oder der Host keine Verbindung zu einem Dienst herstellen können. Ursachen sind vielfältig: falsche Portfreigaben, Netzwerkeinstellungen, Firewall-Regeln oder Dienste, die im Container noch nicht gestartet sind. In diesem Artikel erklären wir praxisnah die typischen Gründe und schnelle Lösungen, um die Erreichbarkeit von Containern und Services wiederherzustellen.

Table of Contents

Typische Ursachen für “Connection refused”

Dienst im Container läuft nicht: Container gestartet, aber Service (z. B. Datenbank oder Webserver) ist noch nicht aktiv.
Port nicht veröffentlicht: Bridge-Netzwerke erfordern explizites Port-Mapping.
Firewall blockiert Zugriff: Host-Firewall (iptables, ufw, nftables) verhindert Verbindung.
Falsches Netzwerk: Container befinden sich in unterschiedlichen Netzwerken.
DNS oder Hostname falsch: Container versuchen, falschen Namen oder IP zu erreichen.

Dienststatus im Container prüfen

Oft ist der Service selbst nicht gestartet. Überprüfen Sie den Status:

docker ps
docker logs 
docker exec -it  /bin/sh
# z. B. Webserver prüfen
ps aux | grep nginx
ps aux | grep postgres

Logs geben Hinweise auf fehlgeschlagene Starts
Interaktive Shell erlaubt manuelles Starten und Testen

Port-Mapping überprüfen

Bridge-Netzwerke benötigen explizite Portfreigaben:

docker ps
docker port

Beim Starten eines Containers sollten Ports korrekt gemappt sein:

docker run -d -p 8080:80 myorg/web:1.0.0

Host-Port 8080 wird auf Container-Port 80 weitergeleitet
Fehlt das Mapping, ist der Dienst von außen nicht erreichbar

Netzwerk überprüfen

Container in verschiedenen Netzwerken können sich nicht per Namen erreichen:

docker network ls
docker network inspect

Container müssen im gleichen Netzwerk sein oder ein Overlay nutzen
Nachträgliches Verbinden möglich: docker network connect

Firewall und Sicherheitsregeln prüfen

Firewalls verhindern oft die Verbindung:

# iptables prüfen
sudo iptables -L -n
sudo iptables -t nat -L -n

# ufw prüfen
sudo ufw status verbose

Bridge-Netzwerkports freigeben
Overlay-Netzwerke: Routing zwischen Hosts überprüfen
Host-Schutzmechanismen wie SELinux oder AppArmor ggf. konfigurieren

DNS und Container-Namen testen

Docker nutzt internes DNS. Prüfen Sie die Namensauflösung:

docker exec -it  ping 
docker exec -it  nslookup

Falsche Hostnamen führen zu “Connection refused”
In Compose: depends_on und networks korrekt definieren

Healthchecks und Startreihenfolge

Manchmal versucht ein Container, auf einen Service zuzugreifen, der noch nicht bereit ist:

version: "3.9"

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

  api:
    image: myorg/api:1.0.0
    depends_on:
      db:
        condition: service_healthy

Healthchecks sorgen dafür, dass abhängige Container erst starten, wenn Services bereit sind
Reduziert “Connection refused” beim Boot

Praktische Debugging-Befehle

Ping zwischen Containern: docker exec -it ping
Netcat zum Testen von Ports: docker exec -it nc -vz
Logs überwachen: docker-compose logs -f
Interaktive Shell für Testzugriffe: docker exec -it /bin/sh

Best Practices zur Vermeidung von “Connection refused”

Netzwerke bewusst planen: Frontend/Backend strikt trennen
Port-Mappings in Bridge-Netzwerken korrekt setzen
Healthchecks für abhängige Services nutzen
Firewall- und Sicherheitsregeln prüfen
Compose depends_on und restart_policy einsetzen
Versionierte Images nutzen und Rollbacks testen
DNS-Auflösung innerhalb von Netzwerken regelmäßig prüfen

Fazit

“Connection refused” in Docker ist ein häufiges Symptom für Netzwerkkonfigurations-, Port- oder Service-Probleme. Durch systematisches Troubleshooting – Prüfung von Ports, Netzwerken, Firewalls, Healthchecks und Logs – können Ursachen schnell identifiziert und behoben werden. Mit klaren Netzwerkstrukturen, Healthchecks und Monitoring lassen sich Ausfallzeiten minimieren und Services zuverlässig verbinden.

Konfiguriere Cisco Router & Switches und liefere ein Packet-Tracer-Lab/GNS3

Ich biete professionelle Unterstützung im Bereich Netzwerkkonfiguration und Network Automation für private Anforderungen, Studienprojekte, Lernlabore, kleine Unternehmen sowie technische Projekte. Ich unterstütze Sie bei der Konfiguration von Routern und Switches, der Erstellung praxisnaher Topologien in Cisco Packet Tracer, dem Aufbau und Troubleshooting von GNS3- und EVE-NG-Labs sowie bei der Automatisierung von Netzwerkaufgaben mit Netmiko, Paramiko, NAPALM und Ansible. Kontaktieren Sie mich jetzt – klicken Sie hier.

Meine Leistungen umfassen:

Professionelle Konfiguration von Routern und Switches
Einrichtung von VLANs, Trunks, Routing, DHCP, NAT, ACLs und weiteren Netzwerkfunktionen
Erstellung von Topologien und Simulationen in Cisco Packet Tracer
Aufbau, Analyse und Fehlerbehebung von Netzwerk-Labs in GNS3 und EVE-NG
Automatisierung von Netzwerkkonfigurationen mit Python, Netmiko, Paramiko, NAPALM und Ansible
Erstellung von Skripten für wiederkehrende Netzwerkaufgaben
Dokumentation der Konfigurationen und Bereitstellung nachvollziehbarer Lösungswege
Konfigurations-Backups, Optimierung bestehender Setups und technisches Troubleshooting

Benötigen Sie Unterstützung bei Ihrem Netzwerkprojekt, Ihrer Simulation oder Ihrer Network-Automation-Lösung? Kontaktieren Sie mich jetzt – klicken Sie hier.