> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Demo Debugging a Failed Deployment > Guide for diagnosing and troubleshooting failed AWS CodeBuild runs using phase timelines CloudWatch logs permission checks and the interactive debug sandbox to identify and fix common deployment errors. 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: ```console theme={null} ACCESS_DENIED: Service role arn:aws:iam::598274344262:role/devops-020-430-build-e24d346a does not allow AWS CodeBuild to create Amazon CloudWatch Logs log streams for build arn:aws:codebuild:us-east-1:598274344262:build/devops-020-430-failure:dcdf6e2d-95e5-4319-bff7-97bae88fc175. Error message: User: arn:aws:sts::598274344262:assumed-role/devops-020-430-build-e24d346a/AWSCodeBuild-dcdf6e2d-95e5-4319-bff7-97bae88fc175 is not authorized to perform: logs:CreateLogStream on resource: arn:aws:logs:us-east-1:598274344262:log-group:/aws/codebuild/devops-020-430:log-stream:dcdf6e2d-95e5-4319-bff7-97bae88fc175 because no identity-based policy allows the logs:CreateLogStream action ``` 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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/Demo-Debugging-a-Failed-Deployment/aws-codebuild-devops-020-430-failed.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=cc8cd488ed021c15d19a2bf90fd0a85a) ## Typical CodeBuild phases | Phase | Purpose | | - | - | | Submitted / Queued | Build was received and queued for execution | | Provisioning | Agent initialization and environment setup | | DOWNLOAD\_SOURCE | Source is fetched from the repo or S3 | | INSTALL | Runtime/dependencies installed (e.g., pyenv, apt packages) | | PRE\_BUILD | Pre-build checks and pre-deployment tasks | | BUILD | Main build commands from `buildspec.yml` | | POST\_BUILD | Post-build tasks (tests, packaging, uploads) | | UPLOAD\_ARTIFACTS | Artifacts uploaded to S3 or other stores | | FINALIZING / COMPLETED | Final state and cleanup | ## Example: a build start (phases being discovered and executed) This excerpt shows CodeBuild announcing phases and the commands it runs during setup and build: ```console theme={null} [Container] 2026/03/17 22:52:38.358932 CODEBUILD_SRC_DIR=/codebuild/output/src503240968/src [Container] 2026/03/17 22:52:38.359034 YAML location is /codebuild/readonly/buildspec.yml [Container] 2026/03/17 22:52:38.361099 Processing environment variables [Container] 2026/03/17 22:52:38.595565 Selecting 'python' runtime version '3.12' based on manual selections... [Container] 2026/03/17 22:52:38.596493 Running command echo "Installing Python version 3.12 ..." Installing Python version 3.12 ... [Container] 2026/03/17 22:52:38.603463 Running command pyenv global $PYTHON_312_VERSION [Container] 2026/03/17 22:52:39.444168 Moving to directory /codebuild/output/src503240968/src [Container] 2026/03/17 22:52:39.444195 Cache is not defined in the buildspec [Container] 2026/03/17 22:52:39.488090 Skip cache due to: no paths specified to be cached [Container] 2026/03/17 22:52:39.488372 Registering with agent [Container] 2026/03/17 22:52:39.528913 Phases found in YAML: 4 [Container] 2026/03/17 22:52:39.528934 POST_BUILD: 2 commands [Container] 2026/03/17 22:52:39.528939 INSTALL: 1 commands [Container] 2026/03/17 22:52:39.528943 PRE_BUILD: 2 commands [Container] 2026/03/17 22:52:39.528948 BUILD: 2 commands [Container] 2026/03/17 22:52:39.529416 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED [Container] 2026/03/17 22:52:39.649109 Entering phase INSTALL [Container] 2026/03/17 22:52:39.685086 Running command echo "Installing dependencies..." Installing dependencies... [Container] 2026/03/17 22:52:39.728694 Phase complete: INSTALL State: SUCCEEDED [Container] 2026/03/17 22:52:39.766681 Entering phase PRE_BUILD [Container] 2026/03/17 22:52:39.767849 Running command echo "Running pre-build checks..." Running pre-build checks... [Container] 2026/03/17 22:52:39.775718 Running command echo "All checks passed!" All checks passed! [Container] 2026/03/17 22:52:39.782897 Phase complete: PRE_BUILD State: SUCCEEDED [Container] 2026/03/17 22:52:39.822979 Entering phase BUILD [Container] 2026/03/17 22:52:39.824450 Running command echo "Building application..." Building application... ``` ## 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: ```console theme={null} [Container] 2026/03/17 22:55:52.967220 Phase complete: PRE_BUILD State: SUCCEEDED [Container] 2026/03/17 22:55:53.005125 Entering phase BUILD [Container] 2026/03/17 22:55:53.006303 Running command echo "Building application..." Building application... [Container] 2026/03/17 22:55:53.014079 Running command echo "Build successful!" Build successful! [Container] 2026/03/17 22:55:53.021238 Phase complete: BUILD State: SUCCEEDED [Container] 2026/03/17 22:55:53.056104 Entering phase POST_BUILD [Container] 2026/03/17 22:55:53.057419 Running command echo "Running post-build tasks..." Running post-build tasks... [Container] 2026/03/17 22:55:53.064982 Running command echo "Deployment ready!" Deployment ready! [Container] 2026/03/17 22:55:53.072525 Phase complete: POST_BUILD State: SUCCEEDED [Container] 2026/03/17 22:55:53.169804 Set report auto-discover timeout to 5 seconds [Container] 2026/03/17 22:55:53.175134 Assembling file list [Container] 2026/03/17 22:55:53.180078 Expanding file paths for base directory . [Container] 2026/03/17 22:55:53.185597 No matching auto-discover report paths found [Container] 2026/03/17 22:55:53.185721 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED ``` ![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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/Demo-Debugging-a-Failed-Deployment/aws-codebuild-devops-020-430-failure-failed-builds.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=691393e7b0b01bc39c07f0969922c27b) ## 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: ```console theme={null} 2026-03-17T22:55:53.453Z [Container] 2026/03/17 22:55:52.874549 Running command echo "Installing dependencies..." 2026-03-17T22:55:53.453Z Installing dependencies... 2026-03-17T22:55:53.453Z [Container] 2026/03/17 22:55:52.913905 Phase complete: INSTALL State: SUCCEEDED 2026-03-17T22:55:53.453Z [Container] 2026/03/17 22:55:52.949948 Entering phase PRE_BUILD 2026-03-17T22:55:53.453Z [Container] 2026/03/17 22:55:52.951221 Running command echo "Running pre-build checks..." 2026-03-17T22:55:53.453Z Running pre-build checks... 2026-03-17T22:55:53.453Z [Container] 2026/03/17 22:55:52.959817 Running command echo "All checks passed!" 2026-03-17T22:55:53.453Z All checks passed! 2026-03-17T22:55:53.453Z [Container] 2026/03/17 22:55:52.967220 Phase complete: PRE_BUILD State: SUCCEEDED ``` ## Common failure categories and what to check | Failure category | What to look for / actions | | - | - | | Source (repo) problems | Repo access denied, OAuth token expired, wrong branch, webhook misconfigured. Check repo permissions and webhook settings. | | Build stage failures | Missing/misnamed `buildspec.yml`, syntax errors, missing dependencies or build tools, failing tests, out-of-memory errors. Re-run locally if needed. | | Deployment errors | Target environment issues, insufficient instance IAM permissions, KMS access-denied for encrypted artifacts. Review target instance logs and KMS policies. | | Permissions / IAM issues | Missing role policies (e.g., `logs:CreateLogStream`, `s3:GetObject`, `kms:Decrypt`, `iam:PassRole`). Inspect service role and attached identity-based or resource-based policies. | ## 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/`. 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. ## Helpful tips and links * 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: * AWS CodeBuild documentation: [https://docs.aws.amazon.com/codebuild/](https://docs.aws.amazon.com/codebuild/) * Amazon CloudWatch Logs: [https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) * AWS IAM documentation: [https://docs.aws.amazon.com/IAM/latest/UserGuide/](https://docs.aws.amazon.com/IAM/latest/UserGuide/) 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](https://learn.kodekloud.com/user/courses/aws-certified-devops-engineer-professional/module/199ecdf9-a58f-4c2d-b9c9-eac36de111cd/lesson/60884f89-0ac2-4175-b4b2-451ce646b638)** > **[Practice Lab](https://learn.kodekloud.com/user/courses/aws-certified-devops-engineer-professional/module/199ecdf9-a58f-4c2d-b9c9-eac36de111cd/lesson/3453f5a1-e551-4b36-a1a3-692259394256)** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.