Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

curl exits with code 7: connection refused on Linux

Errorcurl: (7) Failed to connect to host

Short 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.

  • Applies to curl 8.x, iproute2 ss, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 -ltnp
  2. 2Match what you see, then jump to its fix

    1. 1ss -ltnp has no line for the port in the URL.Nothing listens on that port, or the URL has the wrong portFix
    2. 2The service works from the server itself but curl from another machine exits with 7.A firewall rejects the connectionFix
    3. 3curl 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

What does the error look like?

  • curl: (7) Failed to connect to host
  • Connection 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

Did this fix it?

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 numbered

2Fix

Allow the TCP port you serve on, then check any cloud firewall in front of the machine as well.

sudo ufw allow 8080/tcp

3Verify

The request from the other machine now returns a response.

curl -I http://<server-ip>:8080/

Confirmed by ubuntu.com

Did this fix it?

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

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.