Testing a local web server, containerised service, or REST API endpoint in Linux using curl http://localhost:8080 only to be met with the error: ‘curl: (7) Failed to connect to localhost port 8080: Connection refused’ halts local development and deployment testing. In TCP/IP networking, a Connection refused (errno 111 / ECONNREFUSED) error indicates that the kernel network stack reached the target IP address (127.0.0.1 or ::1), but no active process was listening on the designated TCP port, prompting the operating system to send an immediate TCP Reset (RST) packet back to curl.
Why Does curl Return (7) Connection Refused on Localhost?
A TCP RST packet indicates the host exists but no service is bound to that port. Causes include:
- Target Service Is Not Running: The backend web server (e.g. Nginx, Apache, Node.js, Python, or Docker) has stopped, crashed, or failed to start.
- Service Bound to IPv4 vs IPv6 (localhost resolution mismatch): The server listening strictly on
127.0.0.1while curl resolveslocalhostto IPv6::1(or vice versa). - Container Port Mapping Omitted in Docker: Running a Docker container without exposing the port using the
-p HOST:CONTAINERflag. - Service Bound to Wrong Network Interface: The application listening strictly on an internal socket or private IP rather than
0.0.0.0or127.0.0.1. - Local Firewall (iptables / ufw) Blocking Port: Strict loopback firewall rules rejecting local TCP packets.
Step 1: Verify Which Services Are Listening with ss or netstat
Determine whether any active process is actually listening on your requested port.
- Open your terminal and run the socket statistics command:
(Replacesudo ss -tulpn | grep 80808080with your target port number). - Inspect the output:
- If the output is completely blank, no application is listening on that port.
- If an entry is listed, observe the Local Address:Port column (e.g.
127.0.0.1:8080or:::8080).
Step 2: Check Service Status with systemctl
If the service should be running as a background daemon, verify its systemd state.
- Check service status:
sudo systemctl status nginx # Or apache2, docker, etc. - If the service is
inactive (dead)orfailed, restart it:sudo systemctl restart nginx - If it fails to start, inspect recent startup logs:
sudo journalctl -u nginx -e --no-pager
Step 3: Test Direct IPv4 vs IPv6 Explicitly
Because localhost can resolve to both IPv4 (127.0.0.1) and IPv6 (::1), test explicit IP addresses.
- Force curl to use IPv4:
curl -4 -v http://127.0.0.1:8080 - Force curl to use IPv6:
curl -6 -v http://[::1]:8080 - If connecting via
127.0.0.1succeeds, update your application configuration to bind to0.0.0.0(all interfaces) or adjust/etc/hosts.
Step 4: Verify Docker Container Port Mappings
If accessing an application running inside a Docker container, confirm external port publication.
- List running containers and their port configurations:
docker ps - Look at the PORTS column:
- If it displays
8080/tcpwithout a leading host address, the port is only accessible inside the container network. - To access from host localhost, the container must be launched with:
docker run -d -p 8080:8080 image-name
- If it displays
Step 5: Check Local UFW Firewall Loopback Rules
Ensure local firewall policies are not rejecting loopback traffic.
- Check active firewall status:
sudo ufw status verbose - Allow the specific port locally if blocked:
sudo ufw allow in on lo to any port 8080 proto tcp - Re-run your curl request:
curl -I http://localhost:8080
Verifying active socket listeners with ss, restarting failed services, testing IPv4 loopbacks directly, and checking Docker port bindings resolves ‘curl: (7) Connection refused’ in Linux.