Skip to main content
DevOps Insightsguides & answers

curl · troubleshooting

curl: (7) Failed to connect

curl found the host's address but nothing accepted the connection on that port. Usually the service is not running yet, listens on another port or address, or a firewall refuses it.

Reproduced on curl 8.5.0, . Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published

New to this? Read what is actually happening first, then come back to the steps.

On this page · 8 sections

Before you start

  • The host and port from the message, and a shell where the service runs.

Run this first

step 1 of 1
ss -ltnp

Look for The expected port, and the address it is bound to

Lists every listening TCP port and the process behind it, on the machine where the service should run.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

What does ss -ltnp show for that port?

Cause space

3 of 3 still possible

  • The service has not started yet, or has stoppedCommon
  • Wrong port, or the service listens only on 127.0.0.1Common
  • A firewall rejects the connectionOccasional

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Or diagnose it manually

In this order. The first command usually contains the whole answer.

  1. Step 1

    ss -ltnp

    Lists every listening TCP port and the process behind it, on the machine where the service should run.

    Look for The expected port, and the address it is bound to

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

The service has not started yet, or has stopped

Common

A health check or test runs before the app or database finishes starting, or the process crashed.

Confirm

ss -ltnp | grep ':PORT '

No line: nothing is listening on that port

Fix

  • Wait for it properly: curl --retry 10 --retry-delay 2 --retry-connrefused --fail URL.
  • If it should be running, read its logs: it may have exited.
curl --fail --retry 10 --retry-delay 2 --retry-connrefused http://localhost:8080/health

Reproduced on curl 8.5.0 and 8.7.1: without --retry-connrefused, --retry does not retry a refused connection.

Wrong port, or the service listens only on 127.0.0.1

Common

The app listens on a different port, or on 127.0.0.1 inside a container, which other containers and the host cannot reach.

Confirm

ss -ltnp

The real port, and 127.0.0.1 versus 0.0.0.0 in the local address

Fix

  • Use the port the service really listens on.
  • Inside a container, make the app listen on 0.0.0.0, and publish the port if you call it from the host.

A firewall rejects the connection

Occasional

A host firewall rule that rejects (rather than drops) traffic also produces an immediate failure.

Confirm

sudo iptables -S | grep -i reject

A REJECT rule matching the port

Fix

  • Allow the port for the source that needs it.

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

The name resolved, curl knocked on the port, and was turned away at once. That means no program is listening there, or something rejects the connection. In CI it is very often a service that has not finished starting.

Words used on this page

Connection refused
The machine answered that nothing is listening on that port.
Listening address
A server bound to 127.0.0.1 only accepts connections from the same machine or container.
What is actually happening

Reproduced on 23 October 2026 with curl 8.5.0 on Ubuntu 24.04 and curl 8.7.1 on macOS. A port with nothing listening gave curl: (7) Failed to connect to 127.0.0.1 port 18799 after 0 ms: Couldn't connect to server, exit 7. The after 0 ms shows the refusal was immediate.

curl --retry 2 made no retries against it. With --retry-connrefused added, it printed Will retry in 1 seconds twice. curl's manual treats a timeout and HTTP 408, 429, 500, 502, 503 and 504 as transient, and a refused connection only with --retry-connrefused, which is why a wait-for-service loop built on --retry alone does not wait.

How to tell this is your problem
WhereWhat you see
curl 8.xcurl: (7) Failed to connect to localhost port 8080 after 0 ms: Couldn't connect to server

How to know it is actually fixed

  • ss shows the port listening on the right address, and curl gets a response.

Stopping it happening again

  • Wait for services with --retry-connrefused and a bounded --retry, not a fixed sleep.
  • Bind services in containers to 0.0.0.0, and publish only the ports you mean to.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it

Where to go next