Skip to main content
When a CI/CD pipeline fails, the fastest route to resolution is to identify which pipeline stage failed and then drill into the logs for that phase. This guide walks through the systematic process for diagnosing a failed AWS CodeBuild run, how to interpret common error messages, and how to use CloudWatch logs and CodeBuild’s debug sandbox to get interactive diagnostics.

​
Quick overview: find the failing stage first

Start by clicking the failed build in the CodeBuild console. The console shows a phase timeline (Submitted, Queued, Provisioning, DOWNLOAD_SOURCE, INSTALL, PRE_BUILD, BUILD, POST_BUILD, UPLOAD_ARTIFACTS, FINALIZING/COMPLETED). The failing phase and its error message typically point to the root cause. If the build cannot create CloudWatch log streams, the failure is frequently a permissions problem. For example:
That message indicates the CodeBuild service role lacks the CloudWatch Logs actions (for example, logs:CreateLogStream). Updating the service role’s identity-based policy to allow CloudWatch Logs actions on the appropriate log-group resource normally resolves this.
A screenshot of the AWS CodeBuild console showing the build project "devops-020-430-failure" with a red "Failed" status and details like the initiator, start/end times, and Build ARN. The Reports tab is selected and shows no report results.

​
Typical CodeBuild phases

​
Example: a build start (phases being discovered and executed)

This excerpt shows CodeBuild announcing phases and the commands it runs during setup and build:

​
Comparing failing vs. successful runs

Comparing a failing run’s logs against a successful run’s logs highlights what differs: a missing phase, a failed command, or inaccessible resources. Successful build excerpt example:
A screenshot of the AWS CodeBuild console for the project "devops-020-430-failure" showing the build history with multiple failed builds listed and the left-hand developer tools navigation menu.

​
When to open the CloudWatch log stream

  • Click the CloudWatch log link from the build details to view the full log stream.
  • The stream shows detailed, timestamped output from every phase and container command.
  • If the log link is missing or empty, it often means CodeBuild could not create the log stream (permissions) or the run aborted before logs were emitted.
CloudWatch log excerpt example:

​
Common failure categories and what to check

​
Systematic troubleshooting workflow

  1. Identify the failed component (pipeline, stage, or CodeBuild project).
  2. Click the specific run in CodeBuild to view the phase timeline and error text.
  3. Copy the build ID and error message for searches (CloudWatch, CloudTrail, or IAM policy investigations).
  4. If CodeBuild logs are missing, open CloudWatch and look for the log group /aws/codebuild/<project-name>.
  5. Compare the failing run timeline and commands with a known-successful run to isolate differences.
  6. Check for recent changes: IAM policy updates, CI/CD configuration changes, or repository permission changes.
  7. If permissions are suspected, inspect the CodeBuild project’s service role and ensure policies allow required actions.
  8. Use CodeBuild’s interactive debug sandbox (SSH/SSM) to reproduce buildspec steps when local reproduction is difficult.
Start troubleshooting by identifying the failed phase. Most issues fall into permissions, configuration, or dependency categories. Use CloudWatch logs and CodeBuild’s debug sandbox for deeper inspection.
Using CodeBuild’s debug sandbox requires SSM permissions on the role that initiates the sandbox. Ensure the service role has the appropriate SSM IAM actions before launching an interactive session.
  • Always compare timestamps and the sequence of phases between failing and successful runs — differences often surface quickly.
  • Use the build ID when searching CloudTrail or CloudWatch for related events.
  • Consider increasing build memory or running resource-heavy steps in separate jobs if you observe OOM or long-running processes.
References: Summary
  • Identify the failing stage first and read the exact error message.
  • Compare failing runs to successful runs to spot differences.
  • Permissions (CloudWatch Logs, S3, KMS, PassRole) are frequent root causes.
  • Use CloudWatch logs and the CodeBuild debug sandbox for deeper, interactive diagnostics.
  • Follow a systematic workflow to minimize mean time to resolution.
That covers debugging failed CodeBuild builds and common failure patterns.

Watch Video

Practice Lab