Skip to main content
In this lesson we debug a failing AWS CodeBuild run by inspecting the build logs, identifying the root cause, and applying the minimum required IAM changes so CodeBuild can authenticate to Amazon ECR and push Docker images.

​
What happened (quick summary)

The build failed during the pre-build step when CodeBuild attempted to run: aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin <ECR_URI> The error in the logs shows the CodeBuild service role did not have permission to call ecr:GetAuthorizationToken, so authentication to ECR failed and the build exited.

​
Inspecting the CodeBuild logs

Check the CodeBuild logs to find the failing step. The build downloads the source first and then executes the commands in buildspec.yml. Below is an excerpt from the failing run:

​
Root cause

  • The CodeBuild service role (the assumed role in the log) was missing permissions to call ecr:GetAuthorizationToken. Without that action CodeBuild cannot obtain credentials to authenticate Docker to ECR.

​
Fix: grant ECR permissions to the CodeBuild service role

Follow these steps to resolve the issue:
  1. Copy the assumed role ARN from the error message (the assumed-role/... value).
  2. Open the AWS Console → IAM → Roles.
  3. Search for and select the CodeBuild service role shown in the logs.
  4. Click “Attach policies”.
  5. Search for container to find ECR related managed policies.
  6. Select the managed policy AmazonEC2ContainerRegistryPowerUser (this grants the ECR actions CodeBuild needs for build and push).
  7. Click “Add permissions” to attach the policy.
This image shows an AWS IAM console where a user is attaching policies to a service role, with a list of available AWS managed permissions policies related to EC2 Container Registry.
After attaching the policy, re-run the CodeBuild project (Start build) and monitor the logs. The next build should be able to authenticate to ECR and continue.

​
Successful run — authentication, image build, and push

After fixing the role permissions the build logs should show successful ECR login, image creation, tagging, and push. Example successful pre-build and build lines:
The build then shows Docker building the image and pushing layers to ECR. Example push output:
The image shows an AWS CodeBuild interface displaying a successfully completed build project named "aws-microservice-project." It includes build details such as status, initiator, and logs.
You can verify the pushed images in the ECR console — repository tags such as latest and the short commit hash should appear.
The image shows an Amazon Elastic Container Registry (ECR) interface with a private repository named "cryptoproject" successfully created, displaying details like URI and creation date.
For production systems prefer least-privilege policies instead of broad managed policies. Below is a compact mapping of common ECR actions CodeBuild needs and why: Example minimal IAM policy (scope the Resource ARN to your repository where possible). Replace <ACCOUNT_ID> and <REGION> and <REPOSITORY_NAME> with your values:
Notes:
  • ecr:GetAuthorizationToken is a global call that typically requires Resource: "*". You can keep that action broader while scoping the rest to specific repo ARNs if you need tighter permissions.
  • If your builds use image caching or multiple repositories, include those repository ARNs as additional Resource entries.

​
Quick checklist

  • Verify the service role shown in the CodeBuild logs is the role you updated.
  • Attach a managed policy (AmazonEC2ContainerRegistryPowerUser) for quick fixes, or create a scoped custom policy for least privilege.
  • Re-run the build and confirm Login Succeeded and successful docker push.
  • Confirm images and tags appear in the ECR console.
For production environments, prefer granting least privilege. Instead of attaching a broad managed policy, consider creating a custom IAM policy that includes only the specific ECR actions CodeBuild needs (e.g., ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:InitiateLayerUpload, ecr:UploadLayerPart, ecr:CompleteLayerUpload, ecr:PutImage) and scope the resource ARNs to the specific repository.

​
References

This completes the troubleshooting steps for fixing CodeBuild authentication to ECR and getting Docker image pushes working from your build pipeline.

Watch Video