When developing web applications, running Docker containers, or managing reverse proxies (such as Nginx or Apache) in Ubuntu Linux, executing a local cURL command can result in an immediate connection failure: curl: (7) Failed to connect to localhost port 8080: Connection refused. This network socket error indicates that while the local network stack operates properly, no active server process is listening on the specified port, or the listening daemon is bound strictly to an incompatible IP address format (such as IPv6 ::1 vs IPv4 127.0.0.1).
Diagnosing and fixing cURL error 7 requires inspecting active listening sockets with ss or netstat, verifying systemd service daemon status, configuring firewall rules, and resolving IPv4/IPv6 localhost hostname mapping.
Why Does cURL Report Connection Refused on Localhost?
The Linux kernel responds with a TCP RST (reset) packet when a client queries a port where no socket is listening. Common causes include:
- Target Service Is Inactive or Crashed: The underlying daemon (e.g. Node.js, Python Flask/Django, Nginx, or MySQL) stopped, crashed on startup, or failed to start.
- Binding to Specific IP Addresses Instead of 0.0.0.0: The service is listening exclusively on a specific network adapter IP or IPv6 address (
::1), while cURL defaults to IPv4 (127.0.0.1). - Docker Container Port Forwarding Omissions: The container application is listening on internal port 8080, but the Docker daemon was started without the host port mapping parameter (
-p 8080:8080). - Local Firewall (UFW / iptables) Blocking Loopback: Unorthodox firewall rules restricting loopback (
lo) interface traffic. - Corrupted /etc/hosts Mapping: The
localhosthostname does not correctly resolve to127.0.0.1.
Step 1: Check If Any Process Is Listening on the Port
Verify whether a background daemon is actively bound to the target port using the modern ss utility:
- Open a terminal and execute:
(Replacesudo ss -tulpn | grep :80808080with your actual port number, e.g.80,3000, or5000.) - Analyze the output:
- If the output is completely empty, no process is running on that port. Proceed to Step 2 to start your service.
- If it displays
127.0.0.1:8080, the process is bound only to IPv4 loopback. - If it displays
:::8080or[::1]:8080, the process is listening only on IPv6. - If it displays
0.0.0.0:8080, the process is listening across all network interfaces.
Step 2: Inspect and Restart the Target Service via systemd
If your service should be managed by systemd, verify its status and review recent error logs:
- Check the operational state of your service:
(Replacesudo systemctl status nginxnginxwith the name of your service, e.g.apache2,docker, or your custom unit.) - If the status reports inactive (dead) or failed, inspect the execution journal:
sudo journalctl -u nginx -e --no-pager - Restart the service:
sudo systemctl restart nginx - Test the cURL command again:
curl -I http://localhost:80/
Step 3: Test Direct IPv4 vs IPv6 vs Hostname
Mismatches between IPv4 and IPv6 resolution often cause connection refusal when querying localhost:
- Force cURL to connect over explicit IPv4:
curl -4 http://127.0.0.1:8080/ - Test connecting over explicit IPv6:
curl -6 http://[::1]:8080/ - If the IP-based query works while
localhostfails, inspect your/etc/hostsfile:
Ensure the following default lines exist at the top:cat /etc/hosts127.0.0.1 localhost ::1 ip6-localhost ip6-loopback
Step 4: Verify Docker Container Port Mappings
If running services inside Docker containers, confirm container ports are published to the host:
- List running Docker containers:
docker ps - Check the PORTS column for your container.
- If it shows
8080/tcpwithout a host binding arrow (e.g.0.0.0.0:8080->8080/tcp), the port is accessible only within the container internal network. - Restart the container publishing the port to the host:
docker run -d -p 8080:8080 my-image
Step 5: Verify Local UFW Loopback Rules
Ensure that the Ubuntu Uncomplicated Firewall is not inadvertently filtering loopback traffic:
- Check UFW status:
sudo ufw status verbose - Ensure loopback traffic is explicitly allowed:
sudo ufw allow in on lo to any sudo ufw allow out on lo to any - If issues persist, test temporarily disabling UFW:
Run your cURL command to verify if local firewall policies were the root cause.sudo ufw disable