Newman "ECONNREFUSED" because the API is not up yet in CI

By Kaveh Alemi·Latchkey

Newman tried to open a TCP connection to the base URL and the host refused it, so nothing is listening on that host and port yet. In CI this almost always means the API container started but Newman ran before it was ready.

What this error means

Newman fails every request with "Error: connect ECONNREFUSED 127.0.0.1:3000" and the run reports all requests errored. The job races the API startup.

  GET Get user
    Error: connect ECONNREFUSED 127.0.0.1:3000
      at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1595:16)

Common causes

Newman ran before the API finished starting

The service is still booting (migrations, warm-up) when Newman fires, so the port is not accepting connections and the OS refuses the socket.

The base URL host or port is wrong

The environment points at a port the service does not bind, or at localhost when the API runs in a linked service container reachable by a different hostname.

How to fix it

Wait for the API to be ready first

1. Poll the health endpoint until it answers before invoking Newman.
2. Use a readiness loop or a wait tool, not a fixed sleep.
3. Only then run the collection.

- name: Wait for API
  run: |
    for i in $(seq 1 30); do
      curl -sf http://localhost:3000/health && break
      sleep 2
    done
- run: newman run collection.json -e ci.postman_environment.json

Target the correct host for a service container

When the API runs as a services: container, address it by its service name and mapped port, not 127.0.0.1.

newman run collection.json --env-var "baseUrl=http://api:3000"

How to prevent it

• Gate Newman on a health-check readiness loop, never a fixed sleep.
• Confirm the base URL host and port match how the API is exposed in CI.
• Fail the wait step with a clear message if the API never comes up.

Frequently asked questions

Related guides

References

• GitHub Actions documentation