How to Fix: AWS CodeBuild Build Failed to Start

The Scenario

It’s 4:30 PM on a Friday, and you just triggered a CodeBuild project that’s been running fine for weeks. The build immediately fails with “BUILD_FAILED_TO_START” — no logs, no output, just a dead build. You check CloudTrail and see the build was queued but never provisioned an environment.

Symptoms

Build status shows “FAILED” with reason “BUILD_FAILED_TO_START” in the AWS Console or CLI.
Clicking “View logs” returns an empty log stream or a “Log stream does not exist” error.
The build phase never advances past “QUEUED” or “PROVISIONING” — it simply dies.

Root Cause

CodeBuild fails to start when it cannot provision the build environment. This is almost always due to one of three things: the IAM service role lacks permissions to pull the build image or write logs, the VPC configuration (subnets/security groups) is misconfigured or has exhausted IP addresses, or the build project has hit a concurrent build limit. The build is killed silently before any user code runs because the agent can’t boot.

Resolution (Step-by-Step)

Check the build project’s IAM service role permissions. The role needs codebuild:CreateReportGroup, logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents, and ecr:GetAuthorizationToken/ecr:BatchGetImage (if using ECR). Run this to verify:

aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::<account-id>:role/<codebuild-role> \
  --action-names codebuild:CreateReportGroup logs:CreateLogGroup logs:CreateLogStream logs:PutLogEvents ecr:GetAuthorizationToken ecr:BatchGetImage

Verify the VPC configuration if the project uses a VPC. CodeBuild needs at least one available IP address in the subnet and the security group must allow outbound traffic to pull the image (HTTPS on port 443 to the registry). Check subnet IP usage:
```
aws ec2 describe-subnets --subnet-ids <subnet-id> --query 'Subnets[0].AvailableIpAddressCount'
```
If it’s 0, the subnet is full. Also check that the security group egress rules allow 0.0.0.0/0 on port 443.
Check concurrent build limits. CodeBuild has a hard limit of 20 concurrent builds per account (default). If you’re maxed out, new builds fail silently. Check current builds:
```
aws codebuild list-builds --sort-order DESCENDING --query 'ids[:5]' --output text | xargs -I {} aws codebuild batch-get-builds --ids {} --query 'builds[].buildStatus'
```
If you see many “IN_PROGRESS” builds, request a limit increase via the AWS Support Center.
Restart the build with a forced fresh environment. Sometimes a stale Docker cache or corrupted build spec causes this. Invalidate the cache:
```
aws codebuild start-build --project-name <project-name> --invalidate-cache
```

Why This Sometimes Doesn’t Work

Even after fixing IAM and VPC, you may still see the error if the build image is in a private ECR repository in a different AWS account. CodeBuild’s role can’t cross-account pull without an explicit ECR repository policy allowing the role’s ARN. Check the ECR repo policy — it’s a silent blocker that the IAM sim policy won’t catch.

Verification

Trigger a new build and watch the phases:

aws codebuild start-build --project-name <project-name> --query 'build.id'
aws codebuild batch-get-builds --ids <build-id> --query 'builds[0].phases'

Expected output: phases show “SUBMITTED” → “PROVISIONING” → “DOWNLOAD_SOURCE” → “INSTALL” → … → “COMPLETED”. If you see “PROVISIONING” with a status of “FAILED”, the VPC or image pull is still broken.

Common Follow-up Questions

Q: Why does the build fail immediately without any logs? A: The build agent never started, so there’s no container to write logs. The error happens during environment provisioning, before your buildspec runs.

Q: Can I see more detailed error messages? A: Yes, check CloudTrail for the BuildPhaseChange event with a buildPhaseStatus of “FAILED”. The buildPhaseDetail field often contains the actual reason (e.g., “CannotPullContainerError”).

Q: Does this error affect all builds or just some? A: It’s usually per-project. If one project fails but others work, the issue is specific to that project’s IAM role, VPC, or image configuration.

Prevent This in the Future

This error often strikes during peak deployment times when resource limits are hit or after a role rotation breaks permissions. Proactive monitoring of CodeBuild failures and VPC subnet IP utilization would catch this before it blocks a Friday deploy. Set up uptime monitoring and alerts with Better Stack to get notified the moment a build fails to start, so you can fix it before anyone notices. Set up uptime monitoring and alerts with Better Stack