Bitbucket "Container 'Build' exceeded memory limit" (OOM)

By Daniel Zoghalchali·Latchkey

The build container used more memory than its allotment and Bitbucket killed it. Each step gets a fixed memory budget tied to its size (1x/2x), and your process blew past it.

What this error means

The step stops with "Container 'Build' exceeded memory limit." It often coincides with a process being killed (exit 137). It can be intermittent - passing when memory use is just under the line and failing when it tips over.

Container 'Build' exceeded memory limit.

Common causes

The step needs more memory than its size provides

A 1x step gets a fixed RAM budget shared across the build container and any services. A memory-hungry compiler, bundler, or test run exceeds it and triggers the OOM kill.

Service containers consume part of the budget

Services (databases, etc.) draw from the same step memory pool. A heavy service plus a heavy build together can exceed the limit even when neither would alone.

How to fix it

Use a larger step size

Set size: 2x (or higher where available) to roughly double the memory budget for the step.

pipelines:
  default:
    - step:
        name: Build
        size: 2x
        script:
          - npm run build

Reduce the memory the build uses

1. Cap tool heap usage (e.g. NODE_OPTIONS=--max-old-space-size=..., JVM -Xmx).
2. Lower test/build parallelism so fewer processes run at once.
3. Move heavy services to a smaller footprint or a separate step.

Budget memory for services explicitly

Declare a memory allocation for each service so the build container keeps enough headroom.

definitions:
  services:
    postgres:
      image: postgres:16
      memory: 1024

How to prevent it

• Right-size steps with size: 2x for known memory-heavy builds.
• Pin tool heap limits so memory use is predictable.
• Account for service memory when sizing a step.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation