Bitbucket Cloud · Pipelines · Checked November 2, 2026

Bitbucket Pipelines: "Connection refused" to a service container

A service in Pipelines, such as MySQL, PostgreSQL or Redis, runs in its own container next to the build container. The two share one network, so the service opens its port on 127.0.0.1 and your script connects there. When it cannot, the error usually looks like one of these:

psql: error: connection to server at "127.0.0.1", port 5432 failed: Connection refused
ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3306' (111)
Error: connect ECONNREFUSED ::1:5432
psql: error: could not translate host name "postgres" to address: Name or service not known

The step has to list the service

From Atlassian's Databases and service containers: a service is defined once under definitions: services:, and a step gets only the services in its own services: list. The definition alone starts nothing. Every step that connects needs the list, including each step of a parallel group.

definitions:
  services:
    postgres:
      image: postgres:15
      variables:
        POSTGRES_DB: testdb
        POSTGRES_USER: testuser
        POSTGRES_PASSWORD: testpass

pipelines:
  default:
    - step:
        services:
          - postgres
        script:
          - export DATABASE_URL=postgresql://testuser:testpass@127.0.0.1:5432/testdb
          - npm test

127.0.0.1, not the service name

The services share the build container's network adapter, so there is no host name to look up and no port to map. PostgreSQL listens on 5432, MySQL on 3306, Redis on 6379 and MongoDB on 27017. A configuration copied from Docker Compose or GitLab CI, where a service is reached by its name, fails with "could not translate host name" or getaddrinfo ENOTFOUND. Use 127.0.0.1.

The same page recommends 127.0.0.1 over localhost, to avoid IPv6 problems. Some clients look up localhost as the IPv6 address ::1 first, and the error then names it, as in ECONNREFUSED ::1:5432 from Node.js.

The service has not started yet

Pipelines starts the services with the step but does not wait for them: the page lists "no built-in mechanism to wait for service startup" among the limits. A database that is still setting itself up refuses the first connections, and tests that start at once fail. Atlassian's examples wait in an until loop before the tests. With a counter, the step gives up after about a minute instead of looping until the time limit:

script:
  - |
    for i in $(seq 1 30); do
      pg_isready -h 127.0.0.1 && break
      sleep 2
    done
  - pg_isready -h 127.0.0.1
  - npm test

The last pg_isready fails the step if the database never came up. The check needs a client in the build image. Atlassian's other examples use mysql -h 127.0.0.1 ... -e "SELECT 1", redis-cli -h 127.0.0.1 ping and curl -f on a health URL; if the image does not have them, the loop prints "command not found" on every pass.

The service never started

When a service container fails to start, the build log may not say so. An Atlassian issue opened in March 2026, BCLOUD-24054, asks for a clear message there and is still gathering interest. The reason is in the service's own log: in the step's log view, Atlassian's post of October 29, 2026 on the refreshed Pipelines pages says service logs are now grouped in a dropdown.

The official postgres image does not start without POSTGRES_PASSWORD (or POSTGRES_HOST_AUTH_METHOD: trust).
The official mysql image needs one of MYSQL_ROOT_PASSWORD, MYSQL_ALLOW_EMPTY_PASSWORD or MYSQL_RANDOM_ROOT_PASSWORD. When the password comes from a repository variable, check that it is set (a variable is empty).
Memory. Each service gets 1024 MB unless its definition sets memory (128 to 3072 MB), and the page's troubleshooting section checks that first. Atlassian's Elasticsearch example sets memory: 2048 and a 512 MB Java heap (ES_JAVA_OPTS: '-Xms512m -Xmx512m'). The step's total does not grow: 4 GB at 1x, shared with the build container (how the memory is split).

From inside docker run

127.0.0.1 is the build container's address. A container that your script starts with docker run has its own localhost, and the service is not there. Atlassian's article Connecting to a service container while inside a Docker container (updated September 26, 2025) starts the container with --add-host=host.docker.internal:host-gateway and connects to host.docker.internal on the service's port. The step lists both the service and docker:

- step:
    services:
      - postgres
      - docker
    script:
      - docker run --add-host=host.docker.internal:host-gateway my-app \
          psql postgresql://testuser:testpass@host.docker.internal:5432/testdb

Five services, and not port 29418

A step can have up to 5 services, and a service cannot use port 29418. Atlassian's article on "Failed to connect to localhost port 29418" shows why: Pipelines points git at an internal proxy on localhost:29418 so the step can push back to its repository.

Bitbucket Pipelines in IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window, with their steps, the failed step and the command it stopped at, and the step's log as Bitbucket writes it. The list, steps and logs are free; running, re-running and stopping pipelines are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; Docker is a trademark of Docker, Inc.; MySQL is a trademark of Oracle; PostgreSQL is a trademark of the PostgreSQL Community Association; Redis is a trademark of Redis Ltd.; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian, Docker, Oracle, the PostgreSQL Community Association, Redis or JetBrains.

More: "Not authorized to perform sts:AssumeRoleWithWebIdentity" (OIDC to AWS) · Test results not showing · A variable is empty · "Host key verification failed" (SSH) · "Cannot connect to the Docker daemon" · "authorization denied by plugin pipelines" (Docker) · "Container 'docker' exceeded memory limit." · Pipelines did not run after a push · "Container 'Build' exceeded memory limit." · "Exceeded build time limit of 120 minutes" · The cache is not used · "unexpected system error" · "command not found" · Submodules not cloned · "We couldn't clone the repository" · "No online runner available" · "No space left on device" · "Step exceeded processing limits" · The artifact is missing in the next step · The build passed before and fails now · Build setup takes too long · "You've run out of build minutes" · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · "Container 'build' failed to pull image" · The scheduled pipeline did not run · Bitbucket Pipelines plugins for IntelliJ IDEA, compared · 日本語