GitHub Actions service container "could not connect on mapped port"

A step tried to reach a service container but the host or port was wrong. From a container job the service is reachable by its label name; from a job running directly on the runner you must use a mapped host port on localhost. On Latchkey managed runners, transient connection failures during service startup are auto-retried.

What this error means

A test or migration step fails with connection refused or timeout when talking to a service container.

Error: connect ECONNREFUSED 127.0.0.1:5432
##[error]Process completed with exit code 1.

Common causes

Wrong host for the execution context

Steps on the runner host reach services via localhost and the mapped port; steps inside a container job reach services by the service label name on the container port.

Port not published

The service did not declare a ports mapping, so no host port forwards to the container.

How to fix it

Publish the port and use the right host

1. Add a ports mapping to the service so the container port is published to the runner.
2. On the runner host, connect to localhost on the mapped port; inside a container job, connect to the service name.
3. Re-run.

services:
  redis:
    image: redis:7
    ports:
      - 6379:6379
steps:
  - run: redis-cli -h 127.0.0.1 -p 6379 ping

How to prevent it

• Publish service ports explicitly when the job runs on the runner host.
• Document whether connections use localhost or the service label per job type.

Related guides