connect() failed (111: Connection refused) while connecting to upstream means NGINX reached the configured destination address but could not establish a TCP connection to the specified port. The usual result for the client is HTTP 502 Bad Gateway. Error 111 is not a generic NGINX failure: it identifies a refused connection to one particular upstream socket. Find that socket in the log, test it from the NGINX network location, and then correct the process, listener, topology, address family, or network policy that is preventing the connection.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What NGINX error 111 actually means
When NGINX proxies a request, a worker opens a connection to the upstream host and port in the loaded configuration. A line such as connect() failed (111: Connection refused) while connecting to upstream records that the connection attempt was actively refused. NGINX’s official logging example includes an upstream value such as http://127.0.0.1:8080/api, errno: 111, and errtext: "Connection refused". In practical terms, no accepting socket completed the connection at that address and port.
As an Amazon Associate I earn from qualifying purchases.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchThe client normally receives a 502 Bad Gateway because NGINX is acting as a gateway and could not reach the selected backend. The upstream: field in the error log is the most useful starting point: it supplies the protocol, host, port and, often, the request path that failed.
Refusal versus timeout
| Log result | What happened | First checks |
|---|---|---|
111: Connection refused |
The target path was reached, but the destination rejected the connection because no suitable listener accepted it or a policy actively rejected it. | Process state, listening port and interface, container or service address, firewall and security policy. |
110: Connection timed out |
Packets were not answered within the connection timeout. The host may be unreachable, silently filtering traffic, or routing incorrectly. | Routes, security groups, firewalls that drop traffic, network policy and proxy_connect_timeout. |
A refusal therefore points first to a closed or mismatched socket; increasing timeouts will not make a process start listening.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Read the failing log line before changing configuration
Capture the complete matching error-log entry and its timestamp. Copy the value after upstream:, including its scheme, address, port and path. Do not substitute the public URL that a user entered; test the exact endpoint NGINX selected. In an upstream group, the line also tells you which peer failed.
connect() failed (111: Connection refused) while connecting to upstream, client: 203.0.113.20, server: example.test, request: "GET /api HTTP/1.1", upstream: "http://127.0.0.1:8080/api", host: "example.test"Use the timestamp to correlate the event with a deployment, container restart, crash, out-of-memory kill or firewall change. A repeated line for one peer is different from one transient failure during a rolling deployment.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Eight-step diagnostic sequence
- Identify the exact upstream. Copy the
upstream:address, protocol, port and time from the error log. This is the destination NGINX actually attempted. - Validate the loaded NGINX syntax. Run
nginx -t. A successful syntax test proves that the configuration parses; it does not prove that a backend is running or reachable. - Inspect the backend listener. On the backend host, run
ss -tlnp. Confirm that the expected process owns the expected port and that it is bound to an interface reachable from NGINX. A process can be running while listening on a different port or only on loopback. - Test TCP reachability from NGINX. Run
nc -zv <host> <port>from the NGINX host. In a container, execute the command inside the NGINX container or its network namespace; a test from your laptop does not represent the proxy’s route. Where netcat is unavailable, an equivalent/dev/tcpcheck can establish whether the socket opens. - Check container or cluster naming. If either side is containerized, verify shared network membership and service discovery. In Kubernetes, resolve and test the Service DNS name from the NGINX pod. In Docker Compose, use the backend service name on the shared Compose network.
- Review network policy. Check the backend host firewall, cloud security group, access-control list and Kubernetes NetworkPolicy for the NGINX source address and destination port. Retest after a rule change.
- Remove address-family ambiguity. If the configuration says
localhost, test both127.0.0.1and::1. Use an explicit address that matches the backend bind rather than relying on resolver order. - Assess peer behavior. For a named upstream group, inspect repeated failures, passive health state and whether another server is available. A single failed peer can be masked temporarily by successful requests to another peer.
Fix the failure class that the checks reveal
The backend stopped, crashed or was killed
Check the service manager, container state or Kubernetes pod status, then inspect recent application, deployment and kernel logs. Look specifically for an out-of-memory kill, a failed migration, an invalid startup configuration or a readiness failure. Start or repair the service only after recording why it stopped; repeatedly restarting a crashing process can hide the cause and create a loop of 502 responses.
After recovery, verify the listener with ss -tlnp and make a direct TCP test from the NGINX location. If a deployment starts NGINX before the backend, change the deployment ordering or readiness handling rather than relying on proxy retries to cover a permanently unavailable service.
The application listens on the wrong port
Compare the port in the loaded NGINX configuration with the port shown by ss -tlnp. A stale environment variable, changed container port, or old deployment value can leave a healthy application on one port while NGINX connects to another. Correct one side so both describe the same socket, then run nginx -t and reload.
The bind address is not reachable from NGINX
A listener on 127.0.0.1 accepts connections only from the same network namespace. It is appropriate when NGINX and the application share a host and namespace, but it is not reachable from a different machine, a separate Docker container or another Kubernetes pod. Bind the backend to a reachable interface, or point NGINX at the address on the network shared by both services. Do not expose a service on all interfaces without applying the required firewall restrictions.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Docker or Kubernetes uses the wrong localhost
127.0.0.1 inside an NGINX container means that NGINX container itself, not the host and not a neighboring application container. In Docker Compose, replace container-local localhost with the backend service name and ensure both services join the same network. In Kubernetes, use the Service DNS name and port; a pod’s loopback interface is private to that pod’s network namespace. Confirm that the Service has ready endpoints and that a NetworkPolicy allows the NGINX pod to connect.
For host access from a container, use the platform’s supported host address or an explicitly routed host interface rather than assuming that localhost refers to the host. The exact address depends on the container runtime and host networking mode, so verify it with a direct TCP test from the NGINX container.
IPv4 and IPv6 do not agree
localhost can resolve to ::1 first while the backend listens only on 127.0.0.1, or the reverse can occur. Test each family explicitly:
nc -zv 127.0.0.1 8080
nc -zv ::1 8080If only one succeeds, configure NGINX with that explicit address or make the backend listen on both families as appropriate. An explicit IPv4 or IPv6 literal removes resolver-order ambiguity and makes future diagnostics unambiguous.
A firewall, ACL or security group blocks the source
Inspect policy from the NGINX host’s perspective. The relevant source may be a host address, container subnet, node address or pod CIDR rather than the end user’s IP. Permit only the required destination port from the NGINX source, then repeat the direct TCP test. A rule that silently drops packets is more likely to produce timeout 110, while an active reject can appear as refusal 111; either requires checking the policy path.
The upstream entry or pass directive is wrong
Run nginx -T to print the complete configuration NGINX loaded, including included files and expanded upstream groups. Compare every server entry with the actual listener. Look for a stale port, misspelled hostname, wrong protocol or an edit made in a file that is not included by the running instance.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Use the directive that matches the backend protocol
For an HTTP reverse proxy, NGINX uses proxy_pass with a hostname or IP and an optional port. The presence of a URI in proxy_pass changes which URI portion is sent upstream, so a syntactically valid line can still target the wrong application path.
location /api/ {
proxy_pass http://127.0.0.1:8080;
}Non-HTTP backends use their corresponding directives: fastcgi_pass for FastCGI, uwsgi_pass for uWSGI, scgi_pass for SCGI and memcached_pass for Memcached. Choosing the wrong *_pass directive or port can produce a refused connection even when the application process is healthy.
Recommended Free Tools
For TCP proxying, define an upstream group whose server entries include obligatory port numbers:
stream {
upstream game_backend {
server 10.0.0.21:9000;
server 10.0.0.22:9000;
}
server {
listen 9000;
proxy_pass game_backend;
proxy_connect_timeout 5s;
}
}proxy_connect_timeout limits connection establishment; it does not open a closed port. If the upstream accepts traffic only from a particular source interface, proxy_bind can select that local address, provided routing and policy permit it.
Configuration correction and safe reload
- Edit the configuration or included file that
nginx -Tshows as active. - Recheck the destination address, port, protocol directive and, for HTTP, the intended URI behavior of
proxy_pass. - Run
nginx -tand stop if validation fails. - Reload only after a successful test, using the service manager or NGINX reload mechanism used by your installation.
- Repeat a direct TCP test and make a request through NGINX while watching the error and access logs.
- Confirm that the response is now produced by the intended backend and that no second upstream or address-family failure is being selected.
A reload applies configuration without requiring a full process stop, but it cannot repair a backend that is still down, an unreachable network, or a closed listener.
Upstream groups, retries and passive health
Named upstream groups support round-robin distribution, server ports and passive health behavior. When a connection fails, NGINX can retry another configured peer according to the proxy and upstream settings. With multiple peers, users may see successful responses while one backend remains broken; inspect logs and peer state rather than assuming the problem has disappeared. With one upstream server, there is no alternate peer, so a refused connection generally reaches the client as a 502 immediately.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Retries are a resilience mechanism, not a repair for a consistently closed port. Fix the failed service, listener or route and then verify every peer individually. During a rolling deployment, use readiness checks and controlled removal from the upstream group so new requests are not sent to a process before it accepts connections.
Choose the remedy by topology
| Topology | Likely mistake | Verification | Durable fix |
|---|---|---|---|
| NGINX and backend on one host | Wrong port, stopped process or loopback/IPv6 mismatch. | ss -tlnp; test 127.0.0.1 and ::1. |
Repair the service, align the port and use the address family the process actually binds. |
| Separate hosts | Backend bound only to loopback or a network policy blocks NGINX. | Run nc -zv from the NGINX host and inspect routes and policy. |
Bind to a reachable interface and allow only the NGINX source to the backend port. |
| Docker Compose | NGINX uses container-local localhost or services lack a shared network. |
Resolve the Compose service name and test from the NGINX container. | Use the service name on a shared network and the container’s listening port. |
| Kubernetes | NGINX targets pod loopback, the Service has no ready endpoints, or NetworkPolicy denies traffic. | Resolve the Service DNS name from the NGINX pod; inspect endpoints and policy. | Use Service discovery, publish the correct target port and permit the NGINX source. |
Useful command checklist
nginx -t— parse and validate the configuration.nginx -T— print the complete loaded configuration, including included files and upstream definitions.ss -tlnp— show listening TCP sockets and owning processes on the backend host.nc -zv <host> <port>— test TCP connection establishment from the NGINX network location.nc -zv 127.0.0.1 <port>andnc -zv ::1 <port>— compare IPv4 and IPv6 loopback behavior.
Run each command in the namespace that makes the connection: a host test cannot prove that a container or pod can reach the same destination. Preserve the output with the corresponding log timestamp so a later deployment or policy change can be correlated accurately.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Do not mistake a quick workaround for a fix
Changing proxy_connect_timeout, adding retries, or restarting NGINX may alter the symptom without changing the failed socket. A refusal is generated before HTTP headers, authentication, application routing or request payloads are involved. Focus first on whether a process owns the port and whether the NGINX source can reach it. Only after the TCP connection succeeds should you investigate URI rewriting, upstream response codes, TLS settings or application-level health.
Likewise, testing from the backend host can give a false sense of security. A loopback test proves only that the service accepts that host’s local connection. Test the exact address NGINX uses, from the same host, container, pod or node network namespace. If DNS returns multiple addresses, test each returned address or temporarily use the literal shown in the log so a healthy address does not hide a broken one.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsWhat to record during an incident
Keep the first failing log line, the loaded configuration, listener output and direct-connect result together. Record whether the failure affects every request or only one upstream peer, whether it began at a deployment time, and whether IPv4 and IPv6 behave differently. This evidence distinguishes a stopped process from a stale port, a namespace mistake, and a policy rejection. After the repair, repeat the same commands and retain the successful results for the next change window.
Further reading
NGINX Cookbook, 2nd Edition by Derek DeJonghe (O’Reilly Media, May 2022) is a 202-page reference covering installation, HTTP/TCP/UDP load balancing, passive health checks and debugging techniques.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Frequently Asked Questions
What does “connect() failed (111: Connection refused) while connecting to upstream” mean?
NGINX tried to open a TCP connection to the host and port shown in the upstream: field, but no accepting socket completed the connection. Check the process, listener, bind address and network policy for that exact destination.
Why does NGINX return 502 for error 111?
The proxy could not connect to the selected backend, so it cannot obtain a valid upstream response. NGINX commonly reports that gateway failure to the client as HTTP 502 Bad Gateway.
How can I tell whether the upstream port is listening?
Run ss -tlnp on the backend host and verify the expected process owns the expected port and interface. Then run nc -zv host port from the NGINX host or container, not only from your workstation.
Why does localhost work on the host but fail in Docker?
Each container has its own network namespace. 127.0.0.1 inside the NGINX container points back to that container, not to the host or another container. Use the backend service name on a shared Docker network and test from inside NGINX.
How do I fix an IPv4/IPv6 localhost mismatch?
Test 127.0.0.1 and ::1 separately. Configure NGINX with the address family on which the backend listens, or configure the backend to listen on both families when that is appropriate.
Can retries permanently solve connection refused errors?
No. Multiple upstream peers may let NGINX retry a healthy server and temporarily mask one failed peer, but retries cannot repair a consistently closed port. With one peer, the request generally returns 502 immediately.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Does nginx -t prove that the backend is reachable?
No. nginx -t validates NGINX configuration syntax. Use nginx -T to inspect the active upstream definition, then use ss and a direct TCP test to establish process and network reachability.
Which NGINX directive should I use for a non-HTTP backend?
Use the directive matching the protocol: proxy_pass for HTTP, fastcgi_pass for FastCGI, uwsgi_pass for uWSGI, scgi_pass for SCGI, memcached_pass for Memcached, and an upstream group with proxy_pass in the stream context for TCP proxying.
The Bottom Line
Error 111 is a precise upstream socket failure, not a vague NGINX problem. Copy the logged upstream address, validate the loaded configuration, confirm the backend listener, test from NGINX’s network namespace, and then fix the process, port, bind address, topology or policy that failed. Reload only after nginx -t succeeds, and verify every upstream peer after recovery.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
