Bitbucket Service Container Failed to Start in a Step

By Kaveh Alemi·Latchkey

A service container attached to the step did not come up cleanly - it crashed on bad config, or your script connected before it finished booting - so the connection is refused.

What this error means

The script fails connecting to a service (connection refused on the service host/port) even though the service is declared. Sometimes it passes on retry, which points at a startup race rather than a config error.

psql: error: connection to server at "localhost" (127.0.0.1),
port 5432 failed: Connection refused
Is the server running on that host and accepting connections?

Common causes

Script connects before the service is ready

Bitbucket starts the service alongside your script. A database can take a few seconds to accept connections; a script that connects immediately races the startup and gets refused.

Service crashes on bad configuration

Missing required env vars (e.g. no MYSQL_ROOT_PASSWORD), an unsupported image tag, or too little memory makes the service container exit before it ever listens.

How to fix it

Wait for the service before using it

Poll the service until it accepts connections instead of connecting blindly.

script:
  - until pg_isready -h localhost -p 5432; do sleep 1; done
  - ./run-db-tests.sh

Give the service its required config and memory

Provide the env vars the image needs and enough memory so it does not crash.

definitions:
  services:
    postgres:
      image: postgres:16
      memory: 1024
      variables:
        POSTGRES_PASSWORD: test

How to prevent it

• Add a readiness wait before the first connection to a service.
• Supply every required env var for the service image.
• Allocate enough memory: so the service does not OOM at boot.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation