nginx: connect() failed (111: Connection refused)

So sieht die Meldung aus

connect() failed (111: Connection refused) while connecting to upstream, client: 198.51.100.7, server: app.example.com, upstream: "http://127.0.0.1:3000/"

Häufige Ursachen

Backend-Dienst ist abgestürzt, gestoppt oder startet gerade neu.
Backend lauscht auf einem anderen Port oder nur auf einer anderen Adresse.
proxy_pass nutzt localhost, das zu ::1 auflöst, die App lauscht aber nur auf 127.0.0.1.
Docker-Container gestoppt oder Port nicht veröffentlicht.
Nach Deploy zeigt die Konfiguration auf einen alten Port.

Prüfen

Prüfen, ob auf dem Port etwas lauscht
ss -ltnp | grep -E ':3000\b'
Backend direkt ohne nginx ansprechen
curl -sv http://127.0.0.1:3000/ -o /dev/null
Upstream-Ziele in der nginx-Konfiguration anzeigen
nginx -T 2>/dev/null | grep -nE 'proxy_pass|fastcgi_pass|server .*:[0-9]+'
Status und letzte Logzeilen des Backend-Dienstes anzeigen
systemctl status app.service --no-pager -l

Lösung

Backend starten und im Journal prüfen, warum es beendet wurde.
In proxy_pass die IP verwenden, auf der die App wirklich lauscht, z. B. http://127.0.0.1:3000 statt localhost.
Port in App-Konfiguration und nginx abgleichen, danach nginx -t && systemctl reload nginx.
Bei Docker den Port mit -p 127.0.0.1:3000:3000 veröffentlichen oder nginx ins selbe Netzwerk hängen.
Dienst mit Restart=on-failure absichern, damit ein Absturz nicht stundenlang 502 liefert.

Häufige Fragen

Was ist der Unterschied zu „upstream timed out (110)“?

111 heißt: Niemand lauscht, die Verbindung wird sofort abgelehnt. 110 heißt: Das Backend lauscht, antwortet aber nicht rechtzeitig – das ergibt 504.

Warum tritt der Fehler nur kurz nach einem Deploy auf?

Der Dienst braucht einige Sekunden zum Start. In dieser Zeit lehnt das System Verbindungen ab. Abhilfe: Health-Check vor dem Umschalten oder mehrere Instanzen.

nginx: connect() failed (111: Connection refused) to upstream