Bitbucket Service X Failed to Start (memory)

By Daniel Zoghalchali·Latchkey

A service container (database, queue, etc.) failed to start because it exceeded its memory allocation and was OOM-killed before listening. The script that depends on it then cannot connect.

What this error means

A service is reported as failing to start, or the script gets connection-refused from a service that never came up. Raising the service memory (and step size) lets it boot.

Service 'elasticsearch' failed to start: container exceeded its
memory limit during startup.

Common causes

Service memory budget too low

Memory-heavy services (Elasticsearch, large databases) need more than the default service allocation, or they OOM at boot.

Step total exhausted by build + services

The step's memory is shared across the build container and all services. Too many services, or a small step, starves the service at startup.

How to fix it

Increase service memory and step size

Raise the service memory and use a larger step so it has headroom to boot.

definitions:
  services:
    elasticsearch:
      image: elasticsearch:8.13.0
      memory: 2048
      variables:
        ES_JAVA_OPTS: '-Xms1g -Xmx1g'
pipelines:
  default:
    - step:
        size: 2x
        services: [ elasticsearch ]
        script: [ ./test.sh ]

Trim concurrent services

Run fewer services per step so each gets enough of the budget.

How to prevent it

• Allocate enough memory to memory-heavy services.
• Keep the number of concurrent services small.
• Tune service heap settings to fit the allocation.

Frequently asked questions

Related guides

References

• GitHub Actions documentation