curl exits with code 7: connection refused on Linux
curl: (7) Failed to connect to hostShort answer
Curl found the host's address and tried to open a TCP connection, but nothing accepted it. Check whether anything listens on that port with ss, make sure the port and host in the URL are right, look at the firewall, and try curl -4 and -6 to rule out an address family mismatch.
Fix it fast
1Find out which cause you have
Run curl verbosely to see which address and port it tried, then ask the server machine what is listening on TCP ports. The pair of answers separates the causes below.
curl -v http://localhost:8080/ sudo ss -ltnp2Match what you see, then jump to its fix
- 1
ss -ltnp has no line for the port in the URL.Nothing listens on that port, or the URL has the wrong portFix - 2
The service works from the server itself but curl from another machine exits with 7.A firewall rejects the connectionFix - 3
curl http://localhost:PORT fails, while curl http://127.0.0.1:PORT or http://[::1]:PORT works.The hostname resolves to an address family the service does not useFix
- 1
What does the error look like?
curl: (7) Failed to connect to hostConnection refused
Cause 1 of 3
Nothing listens on that port, or the URL has the wrong port
1Check
The ss flags used here show only listening TCP sockets, with numeric ports and the process that owns them. Exit code 7 is documented as a failed TCP connection setup, with a wrong port or hostname among the usual reasons.
sudo ss -ltnp | grep ':8080'2Fix
Start the service, or change the URL to the port it really uses (the ss output shows it).
sudo systemctl status my-app
sudo systemctl start my-app
curl -I http://localhost:3000/3Verify
ss lists the port and curl returns headers.
sudo ss -ltnp | grep ':3000'
curl -I http://localhost:3000/Confirmed by everything.curl.dev
Cause 2 of 3
A firewall rejects the connection
1Check
The same exit code documentation names a firewall blocking the traffic. On Ubuntu, ufw is the usual front end, so list its rules.
sudo ufw status numbered2Fix
Allow the TCP port you serve on, then check any cloud firewall in front of the machine as well.
sudo ufw allow 8080/tcp3Verify
The request from the other machine now returns a response.
curl -I http://<server-ip>:8080/Confirmed by ubuntu.com
Cause 3 of 3
The hostname resolves to an address family the service does not use
1Check
A name can resolve to both IPv4 and IPv6 addresses. Force one family at a time with -4 and -6 and compare the results.
curl -4 -sS -I http://localhost:8080/
curl -6 -sS -I http://localhost:8080/2Fix
Make the service listen on the family you connect with, or connect with an explicit address or the matching flag. -4 asks only for IPv4 addresses and -6 only for IPv6.
curl -4 http://localhost:8080/
curl http://127.0.0.1:8080/3Verify
The working form returns a response; use it in scripts and config.
curl -4 -I http://localhost:8080/Confirmed by curl.se
How do I stop it coming back?
- Write the full address and port in config files instead of relying on localhost.
- Check listeners with ss after every deploy, not only the service status.
- Keep firewall rules in a script or config management so they are not lost on rebuild.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Servers
nginx 502 Bad Gateway in front of a Node.js app
connect() failed (111: Connection refused) while connecting to upstream
A 502 means nginx reached for your Node.js app and got nothing usable back.
5 causes, each with a fixServers
dnf cannot install MySQL on Amazon Linux 2023
dnf cannot find a mysql-server package on Amazon Linux 2023
Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.
3 causes, each with a fixServers
Ansible hangs, then times out waiting for the sudo prompt
a playbook using become seems to hang
Ansible ran sudo on the target and never saw the answer it expected.
3 causes, each with a fixServers
Apache on Ubuntu returns 404 Not Found for my site
The requested URL was not found on this server.
On Ubuntu a 404 from Apache usually means the request maps to a path that has no file.
3 causes, each with a fixServers
Apache returns 504 Gateway Timeout when PHP takes too long
Quick requests work, slow ones end in a 504 after a fixed wait
A 504 from Apache means the backend did not answer within the proxy timeout.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix