CircleCI job killed — resource class memory limit exceeded

What this failure means

The CircleCI job was killed because it exceeded the memory limit of the selected resource class. The process received SIGKILL or the container was OOM-killed by the kernel, and the job exited non-zero without a clear user-visible error.

Symptoms

Faultline looks for one or more of these log fragments:

exit code: 137
Out of memory: Kill process
OOM killer
Killed
Process killed
exit status 137
SIGKILL
java.lang.OutOfMemoryError

Diagnosis

CircleCI jobs run in containers with a fixed memory ceiling determined by the resource class. When the job exceeds that ceiling, the kernel OOM killer terminates one or more processes. The failure typically appears as:

• A process exits with signal 9 (SIGKILL) or a non-zero code with no error message.
• The log ends abruptly or shows Killed without a stack trace.
• CircleCI emits exit code: 137 (128 + SIGKILL).
• A test runner or build tool exits with OOM Killer or Out of memory: Kill process.

Common causes include: large in-memory test suites with too much parallelism, Node.js builds without a --max-old-space-size flag, Docker-in-Docker image pulls inside small containers, or Maven/Gradle builds that default to large JVM heap sizes.

Fix steps

1. Upgrade the resource class in .circleci/config.yml:

   jobs:
     build:
       resource_class: medium+   # or large, xlarge, 2xlarge
   

2. For Node.js builds, cap the V8 heap explicitly:

   - run: NODE_OPTIONS=--max-old-space-size=2048 npm run build
   

3. For JVM-based builds (Maven, Gradle), set a bounded heap:

   MAVEN_OPTS="-Xmx1g" mvn package
   GRADLE_OPTS="-Xmx1g" gradle build
   

4. Reduce test parallelism so each worker uses less memory simultaneously:

   parallelism: 2    # lower from 4 or 8
   

5. Split long test suites across separate jobs and use CircleCI’s test splitting to keep each job within budget.

6. Add a memory monitoring step before the failing command:

   free -h
   

Validation

• Re-run the job and confirm no exit code: 137, Killed, or OOM message appears.
• Verify free -h at job start shows adequate available memory for the workload.

Why it matters

CircleCI containers have hard memory ceilings per resource class. A job that exceeds the ceiling is killed without a user-friendly error message. The exit code 137 is the only reliable signal that memory — not a code bug — caused the failure.

Prevention

• Choose a resource class that provides headroom above the peak observed memory use.
• Set explicit memory caps for JVM and Node.js processes so they fail with a clear error instead of being killed silently.
• Use CircleCI’s test splitting to distribute memory-heavy test suites across parallel containers.
• Monitor peak RSS in each job and set alerts when usage approaches the resource class limit.

Try it locally

free -h
free -h

How Faultline detects it

Use faultline explain circleci-resource-class-oom to see the full playbook.

faultline analyze build.log
faultline explain circleci-resource-class-oom

Generated from playbooks/bundled/log/ci/circleci-resource-class-oom.yaml. Do not edit directly.