CircleCI "Job exceeded the memory limit" (OOM)

By Kaveh Alemi·Latchkey

CircleCI killed the job because its total memory passed the resource class ceiling. Unlike a single "killed" process, this is the whole job exceeding the class RAM budget.

What this error means

The job ends reporting it exceeded the memory limit, often after peak-memory steps (bundling, parallel tests). The same job passes on a larger resource class with no code change.

Job exceeded the memory limit (4GB) for resource class medium.
The container was terminated.

Common causes

Class RAM too small for peak usage

Total resident memory across processes exceeds the class limit (for example 4 GB on medium), so CircleCI terminates the container.

Too much parallelism in one job

Running many workers or test shards in a single job multiplies memory and crosses the ceiling.

How to fix it

Raise the resource class

jobs:
  test:
    docker:
      - image: cimg/node:20.11
    resource_class: xlarge   # more RAM headroom
    steps: [checkout, { run: npm test }]

Reduce in-job memory pressure

1. Lower worker/shard counts to fit the class.
2. Split a memory-heavy job into separate workflow jobs.
3. Profile peak memory and right-size the class to it.

How to prevent it

• Right-size the resource class to real peak memory.
• Avoid packing excessive parallelism into one job.
• Track memory growth as suites and bundles expand.

Frequently asked questions

Related guides

References

• GitHub Actions documentation