AWS CodeBuild Build Failing or Timing Out — Fix Guide

CodeBuild exits with status 1, times out mid-build, or fails with cryptic phase errors. Here's how to diagnose DOWNLOAD_SOURCE, BUILD, and POST_BUILD failures with specific fixes.

Your CodeBuild project fails. The logs show a phase failed but the actual error is buried or missing. Here's how to find the real cause and fix it.

Read the Phase Details First

CodeBuild breaks builds into phases. The failure phase tells you where to look.

bash

# Via CLI
aws codebuild batch-get-builds --ids <build-id> \
  --query 'builds[0].phases[*].{name:phaseType,status:phaseStatus,message:contexts[0].message}'
 
# Or in the console: Build details → Phase details tab

Each phase and what it means:

Phase	What happens	Common failure causes
`DOWNLOAD_SOURCE`	Cloning your repo	Bad credentials, repo not found, S3 access denied
`INSTALL`	Installing runtimes	Wrong runtime version, network issues
`PRE_BUILD`	Pre-build commands	Script errors, missing env vars
`BUILD`	Main build commands	Test failures, compile errors, timeouts
`POST_BUILD`	Push artifacts, deploy	ECR push denied, S3 write denied

Fix 1 — DOWNLOAD_SOURCE Failed

DOWNLOAD_SOURCE: FAILED
"Could not clone repository. Git clone returned exit code 128"

For CodeCommit:

bash

# Check CodeBuild service role has CodeCommit access
aws iam get-policy-version \
  --policy-arn arn:aws:iam::aws:policy/AWSCodeCommitReadOnly \
  --version-id v1
 
# Attach to CodeBuild role if missing
aws iam attach-role-policy \
  --role-name codebuild-my-project-role \
  --policy-arn arn:aws:iam::aws:policy/AWSCodeCommitReadOnly

For GitHub/Bitbucket:

bash

# Verify the connection in CodePipeline/CodeBuild
aws codebuild import-source-credentials \
  --server-type GITHUB \
  --auth-type PERSONAL_ACCESS_TOKEN \
  --token ghp_your_token_here
 
# List existing credentials
aws codebuild list-source-credentials

Fix 2 — Build Timeout

Default CodeBuild timeout is 60 minutes. Long builds (large Docker images, slow tests) exceed this.

bash

# Update timeout
aws codebuild update-project \
  --name my-project \
  --timeout-in-minutes 120

But first — investigate WHY it's slow:

yaml

# In buildspec.yml, add timing to each step
phases:
  build:
    commands:
      - echo "Build start: $(date)"
      - docker build -t myapp .
      - echo "Build end: $(date)"
      - echo "Test start: $(date)"
      - npm test
      - echo "Test end: $(date)"

Fix slow Docker builds with layer caching:

yaml

phases:
  pre_build:
    commands:
      # Pull cache image before building
      - docker pull $ECR_URI/myapp:latest || true
 
  build:
    commands:
      # Use cache-from to reuse layers
      - docker build \
          --cache-from $ECR_URI/myapp:latest \
          -t $ECR_URI/myapp:$CODEBUILD_RESOLVED_SOURCE_VERSION \
          -t $ECR_URI/myapp:latest \
          .

Or use BuildKit cache (faster):

yaml

phases:
  pre_build:
    commands:
      - export DOCKER_BUILDKIT=1
 
  build:
    commands:
      - docker build \
          --build-arg BUILDKIT_INLINE_CACHE=1 \
          --cache-from $ECR_URI/myapp:cache \
          -t $ECR_URI/myapp:$CODEBUILD_RESOLVED_SOURCE_VERSION .

Fix 3 — POST_BUILD Failed: ECR Push Denied

[Container] Phase FAILED: POST_BUILD
"Error response from daemon: denied: User: arn:aws:sts::... is not authorized to perform: ecr:BatchCheckLayerAvailability"

Fix — add ECR permissions to CodeBuild role:

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:PutImage"
      ],
      "Resource": "*"
    }
  ]
}

Also ensure you're logging in to ECR before pushing:

yaml

phases:
  pre_build:
    commands:
      - aws ecr get-login-password --region $AWS_DEFAULT_REGION | \
          docker login --username AWS --password-stdin $ECR_URI

Fix 4 — Environment Variables Not Available

"ERROR: ANTHROPIC_API_KEY is not set"
"KeyError: 'DATABASE_PASSWORD'"

Option 1 — Parameter Store (recommended):

yaml

# In CodeBuild project configuration
env:
  parameter-store:
    DB_PASSWORD: /myapp/prod/db-password
    API_KEY: /myapp/prod/api-key

bash

# Also add IAM permission to CodeBuild role
aws iam attach-role-policy \
  --role-name codebuild-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess

Option 2 — Secrets Manager:

yaml

env:
  secrets-manager:
    DB_PASSWORD: arn:aws:secretsmanager:region:account:secret:myapp/db-password

Fix 5 — Build Fails in VPC — Can't Reach External Services

If your CodeBuild runs inside a VPC (for RDS access, etc.) and can't reach npm/pip/external APIs:

"npm: failed to fetch https://registry.npmjs.org"
"pip: Could not find a version that satisfies the requirement"

VPC CodeBuild needs:

NAT Gateway for internet access (or VPC endpoints for AWS services)
Correct security group — outbound 443 and 80 allowed

bash

# Verify your VPC config has NAT Gateway
aws ec2 describe-nat-gateways \
  --filter "Name=vpc-id,Values=vpc-your-id" \
  --query "NatGateways[*].{ID:NatGatewayId,State:State}"
 
# Check CodeBuild security group outbound rules
aws ec2 describe-security-groups \
  --group-ids sg-your-sg-id \
  --query "SecurityGroups[0].IpPermissionsEgress"

Fix 6 — Exit Status 1 with No Clear Error

Sometimes the build phase shows "exit 1" with no log. This happens when:

A command silently fails and set -e exits immediately
The build container ran out of memory

Enable detailed logging:

yaml

# buildspec.yml
version: 0.2
 
phases:
  build:
    commands:
      - set -euxo pipefail   # Print each command, exit on any error
      - npm ci
      - npm test -- --verbose

Check if OOM killed:

bash

# Check build logs for OOM signs
aws logs get-log-events \
  --log-group-name /aws/codebuild/my-project \
  --log-stream-name $(aws codebuild batch-get-builds --ids $BUILD_ID \
    --query 'builds[0].logs.streamName' --output text) | \
  grep -i "killed\|oom\|memory"
 
# If OOM, increase instance type
aws codebuild update-project \
  --name my-project \
  --environment '{"type":"LINUX_CONTAINER","computeType":"BUILD_GENERAL1_LARGE","image":"aws/codebuild/standard:7.0"}'

CodeBuild instance sizes:

BUILD_GENERAL1_SMALL — 3 GB RAM, 2 vCPU
BUILD_GENERAL1_MEDIUM — 7 GB RAM, 4 vCPU
BUILD_GENERAL1_LARGE — 15 GB RAM, 8 vCPU
BUILD_GENERAL1_2XLARGE — 145 GB RAM, 72 vCPU (for large Docker builds)

For CI/CD labs including CodeBuild, CodePipeline, and GitHub Actions, KodeKloud has AWS DevOps courses covering the full pipeline setup.

AWS CodeBuild Build Failing or Timing Out — Fix Guide

Read the Phase Details First

Fix 1 — DOWNLOAD_SOURCE Failed

Fix 2 — Build Timeout

Fix 3 — POST_BUILD Failed: ECR Push Denied

Fix 4 — Environment Variables Not Available

Fix 5 — Build Fails in VPC — Can't Reach External Services

Fix 6 — Exit Status 1 with No Clear Error

Stay ahead of the curve

Related Articles

AWS ALB 504 Gateway Timeout — Every Cause and Fix (2026)

AWS ALB Showing Unhealthy Targets — How to Fix It

AWS CloudFormation Stack Stuck in ROLLBACK_FAILED: Fix It Now

Comments