Newman "ECONNREFUSED" against localhost before the server is up in CI

Newman opened a connection to your API on localhost and nothing was listening yet. In CI the server is usually started in the same job and Newman runs before it has bound its port, so every request is refused.

What this error means

Newman reports each request as errored with "connect ECONNREFUSED 127.0.0.1:8080" (or your port), and the run ends with all requests failing to connect.

  1.  Error    connect ECONNREFUSED 127.0.0.1:8080
               at request "GET http://localhost:8080/health"

Common causes

The server was not ready when Newman started

The API is launched in the background and Newman runs immediately, before the process binds its port, so the connection is refused.

The server listens on a different host or port

The app binds to a container name or a port other than the one the collection targets, so localhost has nothing listening.

How to fix it

Wait for readiness before running the collection

1. Start the server, then poll a health endpoint until it responds.
2. Only run Newman once the endpoint is reachable.
3. Add a timeout so a truly dead server fails fast.

until curl -sf http://localhost:8080/health; do sleep 2; done
newman run collection.json

Use a service container with a health check

Let the runner gate the job on the service being healthy so Newman never starts too early.

services:
  api:
    image: myorg/api:ci
    ports: ['8080:8080']
    options: >-
      --health-cmd "curl -sf http://localhost:8080/health"
      --health-interval 5s --health-retries 10

How to prevent it

• Poll a health endpoint before any API assertions run.
• Confirm the collection base URL matches the host and port the app binds.
• Use service-container health checks to gate readiness.

Related guides