CircleCI Build Failed: How to Fix OOM, Permission Denied, and Timeout Errors

Understanding Why CircleCI Builds Fail

CircleCI executes your pipeline inside an ephemeral executor — a Docker container, Linux VM, macOS VM, or Windows VM — that is created fresh for every job. Because the environment is isolated and stateless, failures that "never happen locally" are almost always caused by one of four environmental mismatches: resource limits, filesystem permissions, wall-clock timeouts, or missing credentials.

Understanding the exit code in the failing step is the fastest path to the correct fix.

Step 1: Read the Raw Log

Click the failing step name in the CircleCI UI to expand it. Scroll to the very bottom of that step — CircleCI truncates output in the middle but always preserves the final lines where the fatal error appears. Look for:

Killed
Exited with code exit status 137

or

permission denied: ./scripts/deploy.sh
Exited with code exit status 126

or

Too long with no output (exceeded 10m0s): context deadline exceeded

If the log is ambiguous, enable SSH access: open the job in the UI, click Rerun job with SSH, wait for it to start, then copy the SSH command shown and connect. From there you can ls -la, inspect /proc/meminfo, or re-run the failing command interactively.

Step 2: Fix Out-of-Memory (OOM) Failures — Exit Code 137

The Linux OOM killer sends SIGKILL (signal 9) to the process consuming the most memory, which is why you see Killed with no further explanation. Jest, webpack, Gradle, and the JVM are the most common culprits.

Fix A — Upgrade the resource_class:

jobs:
  build:
    docker:
      - image: cimg/node:20.11
    resource_class: medium+   # was: medium (2 vCPU / 4 GB)
    steps:
      - checkout
      - run: npm ci
      - run: npm test

Available Docker resource classes in ascending memory order: small (1 vCPU / 2 GB), medium (2/4 GB), medium+ (3/6 GB), large (4/8 GB), xlarge (8/16 GB), 2xlarge (16/32 GB).

Fix B — Limit Node.js heap size:

- run:
    name: Run Jest with bounded heap
    command: node --max-old-space-size=2048 node_modules/.bin/jest --runInBand
    environment:
      NODE_OPTIONS: "--max-old-space-size=2048"

The --runInBand flag forces Jest to run tests serially rather than forking worker processes, dramatically reducing peak memory.

Fix C — Limit JVM heap for Gradle/Maven:

- run:
    name: Build with bounded JVM
    command: ./gradlew build
    environment:
      JAVA_TOOL_OPTIONS: "-Xmx2g -Xms512m"

Step 3: Fix Permission Denied Errors — Exit Code 126 / EACCES

Permission errors in CircleCI fall into three sub-categories:

3a. Script not executable

If your repo contains shell scripts committed without the executable bit, CircleCI will fail with permission denied. Fix it locally and recommit:

git update-index --chmod=+x scripts/deploy.sh
git commit -m "fix: make deploy script executable"
git push

Alternatively, call bash explicitly inside your config so the executable bit is irrelevant:

- run: bash scripts/deploy.sh

3b. Docker socket or volume permission errors

When running Docker-in-Docker, the circleci user inside the executor may not have access to /var/run/docker.sock. Use the setup_remote_docker step and never mount the host socket directly:

steps:
  - setup_remote_docker:
      version: docker24
      docker_layer_caching: true
  - run: docker build -t myapp:$CIRCLE_SHA1 .

3c. npm / pip global install permission errors

Global installs attempt to write to /usr/local/lib, which requires root. Instead, configure a per-user prefix:

- run:
    name: Configure npm global prefix
    command: |
      mkdir -p ~/.npm-global
      npm config set prefix '~/.npm-global'
      echo 'export PATH=~/.npm-global/bin:$PATH' >> $BASH_ENV
- run: npm install -g your-tool

For pip, prefer pip install --user or use a virtualenv:

- run: pip install --user -r requirements.txt

Step 4: Fix Timeout Errors

CircleCI enforces two independent timeout mechanisms:

1. No-output timeout (default: 10 minutes) — if a step produces no stdout/stderr for 10 minutes, CircleCI kills it.
2. Job-level timeout — free tier jobs are killed after 30 minutes; paid tiers allow up to 5 hours by default.

Fix A — Increase no_output_timeout for long steps:

- run:
    name: Run integration tests
    command: pytest tests/integration/ -v
    no_output_timeout: 30m

Fix B — Force progress output for silent steps (e.g., large downloads):

- run:
    name: Download large artifact with progress
    command: curl -# -o artifact.tar.gz https://storage.example.com/artifact.tar.gz

The -# flag outputs a progress bar, which counts as output and resets the no-output timer.

Fix C — Increase job timeout at the workflow level:

workflows:
  build_and_deploy:
    jobs:
      - build:
          context: production
      - deploy:
          requires:
            - build

Note: per-job wall-clock timeouts require a CircleCI paid plan and are set in the CircleCI project settings UI under Advanced Settings > Maximum Job Runtime.

Step 5: Validate Your Config Before Pushing

Many build failures are caused by YAML syntax errors or invalid config keys that could be caught locally:

# Install the CircleCI CLI
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | bash

# Validate config
circleci config validate .circleci/config.yml

# Pack and validate if using orbs or multiple files
circleci config pack .circleci/ | circleci config validate -

# Process config to see the expanded version
circleci config process .circleci/config.yml

Step 6: Isolate Flaky Failures with Rerun

If a build fails inconsistently (especially on Docker image pulls or npm install), use CircleCI's rerun capabilities:

• Rerun from failed: restarts only the failed job, preserving workspace artifacts from earlier jobs.
• Rerun with SSH: provides an interactive shell for manual investigation.
• Rerun with no cache: forces a clean build, bypassing potentially corrupt caches.

To trigger a no-cache rerun via the API:

curl -X POST \
  --url "https://circleci.com/api/v2/pipeline" \
  --header "Circle-Token: $CIRCLECI_TOKEN" \
  --header "content-type: application/json" \
  --data '{"branch": "main", "parameters": {"run_without_cache": true}}'