How can I troubleshoot a failed CodeDeploy deployment on Amazon EC2 instances?

2 minute read

My AWS CodeDeploy deployment on Amazon Elastic Compute Cloud (Amazon EC2) instances failed.

Short description

You can use the AWS Systems Manager AWSSupport-TroubleshootCodeDeploy Automation runbook to troubleshoot failed deployments. The runbook helps you identify when a deployment fails for the following reasons:

  • The CodeDeploy agent isn't installed or isn't running on the instance.
  • The required instance profile is missing.
  • The instance profile doesn't have correct Amazon Simple Storage Service (Amazon S3) permissions.
  • There's an issue with one of the lifecycle hooks that's managed by CodeDeploy, such as AllowTraffic or BlockTraffic.
  • There's an issue with one of the customer-managed lifecycle hooks.
  • An issue occurred with an Auto Scaling group scale down event during the deployment.
  • An AppSpec file is missing or incorrectly formatted.


Important: Use the AWSSupport-TroubleshootCodeDeploy runbook in the same AWS Region where your CodeDeploy application is located.

1.    Open the AWS Systems Manager console.

2.    In the navigation pane, in the Change Management section, choose Automation.

3.    Choose Execute automation.

4.    On the Owned by Amazon tab, in the Automation document search box, enter AWSSupport-TroubleshootCodeDeploy. Then, select the search icon, or press Enter on your keyboard.

5.    Select the radio button on the AWSSupport-TroubleshootCodeDeploy card.

Note: Make sure that you select the radio button and not the hyperlinked automation name.

6.    In the Document details section, choose Next.

7.    In the Input parameters section, for DeploymentId, enter the deployment ID that failed.

8.    For InstanceID, enter the instance ID where the deployment failed.

9.    For AutomationAssumeRole, enter the Amazon Resource Name (ARN) of the role that allows Systems Manager Automation to perform actions.

Note: If an AWS Identity and Access Management (IAM) role isn’t specified, Systems Manager Automation uses permissions of the IAM user role that runs the runbook. For more information about creating the assume role for Systems Manager Automation, see Task 1: Create a service role for Automation.

Important: Either the AutomationAssumeRole or user role must have permissions for the following actions: codedeploy:GetDeployment, codedeploy:GetDeploymentTarget, and ec2:DescribeInstances.

10.    Choose Execute.

The runbook's output gives troubleshooting steps and recommendations for how to resolve the issue that caused your deployment failure.

Related information

Troubleshooting CodeDeploy

Troubleshoot EC2/on-premises deployment issues

AWS OFFICIALUpdated a year ago