CircleCI Job Timeout

# CircleCI Job Timeout

Common Error Patterns

CircleCI timeout errors typically show:

Job exceeded max execution time of 10 minutes

Step timed out after 5 minutes

Command did not complete within the timeout period

Build exceeded maximum time limit

Root Causes and Solutions

1. Default Timeout Limits

Job exceeds the default 10-minute limit.

Solution:

Increase job timeout in config:

```yaml # .circleci/config.yml version: 2.1

jobs: build: max_build_duration_minutes: 30 # Increase timeout docker: - image: circleci/node:18 steps: - checkout - run: npm install - run: npm build ```

For specific steps:

steps:
  - run:
      name: Long running step
      command: ./long-process.sh
      no_output_timeout: 20m  # Step-specific timeout

2. Insufficient Resource Class

Job runs on small resource class, causing slow execution.

Solution:

Upgrade to larger resource class:

```yaml jobs: build: docker: - image: circleci/node:18 resource_class: large # Upgrade from medium

# Available resource classes: # small (1 CPU, 2GB RAM) # medium (2 CPU, 4GB RAM) # medium+ (3 CPU, 6GB RAM) # large (4 CPU, 8GB RAM) # xlarge (8 CPU, 16GB RAM) # 2xlarge (12 CPU, 32GB RAM) ```

Or use resource class orbs:

```yaml orbs: resource-class: circleci/resource-class@1.0.0

jobs: build: resource_class: large ```

3. Slow Dependencies Installation

Dependencies download and install slowly.

Solution:

Enable caching:

```yaml steps: - restore_cache: keys: - node-deps-v1-{{ checksum "package-lock.json" }} - node-deps-v1-

• run:
• name: Install dependencies
• command: npm ci

• save_cache:
• key: node-deps-v1-{{ checksum "package-lock.json" }}
• paths:
• - ~/.npm
• - node_modules
• `

For multiple dependency sources:

```yaml steps: - restore_cache: keys: - deps-v1-{{ checksum "package-lock.json" }}-{{ checksum "yarn.lock" }}

• run: npm ci
• - run: pip install -r requirements.txt

• save_cache:
• key: deps-v1-{{ checksum "package-lock.json" }}-{{ checksum "yarn.lock" }}
• paths:
• - ~/.npm
• - node_modules
• - ~/.cache/pip
• `

4. No Parallel Execution

Tests run sequentially instead of in parallel.

Solution:

Enable parallelism:

```yaml jobs: test: docker: - image: circleci/node:18 parallelism: 4 # Split across 4 containers

steps: - checkout - run: npm install

• run:
• name: Run tests in parallel
• command: |
• TESTS=$(circleci tests glob "test/**/*.test.js")
• TESTS=$(circleci tests split --split-by file_size --total $CIRCLE_NODE_TOTAL $TESTS)
• npm test $TESTS
• `

Using CircleCI test splitting:

```yaml steps: - run: name: Parallel tests command: | # Automatic splitting circleci tests glob "spec/**/*_spec.rb" | circleci tests split

# Split by timing circleci tests glob "test/**/*.test.js" | \ circleci tests split --split-by timings --timings-type classname ```

5. Large Checkout Time

Repository checkout takes too long.

Solution:

Limit checkout depth:

steps:
  - checkout:
      depth: 1  # Shallow clone, faster checkout

For specific branches:

steps:
  - run:
      name: Fast checkout
      command: |
        git clone --depth 1 --branch $CIRCLE_BRANCH \
          https://github.com/org/repo.git .

6. Docker Build Timeout

Docker image build exceeds timeout.

Solution:

Use pre-built images:

```yaml jobs: build: docker: - image: my-org/my-app:latest # Use cached image

steps: - run: docker push my-org/my-app:$CIRCLE_SHA1 ```

Or optimize Docker build:

steps:
  - run:
      name: Build Docker image
      command: |
        docker build \
          --build-arg BUILDKIT_INLINE_CACHE=1 \
          --cache-from my-org/my-app:latest \
          -t my-org/my-app:$CIRCLE_SHA1 .
      no_output_timeout: 30m

7. Waiting for External Services

Job waits for slow external services.

Solution:

Use proper retry patterns:

steps:
  - run:
      name: Wait for service
      command: |
        until curl -s http://service:8080/health > /dev/null; do
          echo "Waiting for service..."
          sleep 5
        done
      no_output_timeout: 5m

Use CircleCI wait-on orb:

```yaml orbs: wait: circleci/wait-on@1.0.0

steps: - wait/on: endpoint: http://localhost:8080/health timeout: 60 ```

8. Workflow Step Timeout

Entire workflow exceeds time limit.

Solution:

Set workflow timeout:

```yaml workflows: version: 2 build-and-test: jobs: - build - test: requires: - build

workflows: build-and-test: max_build_duration_minutes: 60 # Workflow-level timeout jobs: - build - test ```

Resource Optimization

Compare Resource Classes

```yaml # Performance comparison jobs jobs: test-small: resource_class: small steps: [run: npm test]

test-large: resource_class: large steps: [run: npm test] ```

Use GPU for ML Jobs

jobs:
  train-model:
    docker:
      - image: circleci/python:3.9-gpu
    resource_class: gpu.nvidia.medium
    steps:
      - run: python train.py

Debugging Commands

```bash # View job details curl -s https://circleci.com/api/v2/project/gh/org/repo/job/:job-id \ --header "Circle-Token: $TOKEN"

# Get job output curl -s https://circleci.com/api/v1.1/project/gh/org/repo/:build-num/output \ --header "Circle-Token: $TOKEN"

# Cancel job curl -X POST https://circleci.com/api/v2/project/gh/org/repo/job/:job-id/cancel \ --header "Circle-Token: $TOKEN" ```

Timeout Quick Reference

Optimization Checklist

Prevention Tips

1. 1.Monitor job duration with insights
2. 2.Use appropriate resource class for job type
3. 3.Enable caching for all dependencies
4. 4.Split tests across parallel containers
5. 5.Set appropriate timeouts per step
6. 6.Use Docker layer caching

Related Articles

• [GitHub Actions Workflow Failed](#)
• [GitLab CI Pipeline Stuck](#)
• [Test Coverage Threshold Not Met](#)