AWS CodeDeploy
User Guide (API Version 2014-10-06)

A new console design is available for this service. Although the procedures in this guide were written for the older version of the console, you will find many of the concepts and basic procedures in this guide still apply.

General Troubleshooting Issues

General Troubleshooting Checklist

You can use the following checklist to troubleshoot a failed deployment.

  1. See View Deployment Details with AWS CodeDeploy and View Instance Details to determine why the deployment failed. If you are unable to determine the cause, continue to the rest of the items in this checklist.

  2. Check whether you have correctly configured the instances:

  3. Check the application and deployment group settings:

  4. Confirm the application revision is correctly configured:

  5. Check whether the service role is correctly configured. For information, see Step 3: Create a Service Role for AWS CodeDeploy.

  6. Confirm you followed the steps in Getting Started with AWS CodeDeploy to:

    • Attach policies to the IAM user.

    • Install or upgrade and configure the AWS CLI.

    • Create an IAM instance profile and a service role.

    For more information, see Authentication and Access Control for AWS CodeDeploy.

  7. Confirm you are using AWS CLI version 1.6.1 or later. To check the version you have installed, call aws --version.

If you are still unable to troubleshoot your failed deployment, review the other issues in this topic.

AWS CodeDeploy deployment resources are supported in certain regions only

If you do not see or cannot access applications, deployment groups, instances, or other deployment resources from the AWS CLI or the AWS CodeDeploy console, make sure you're referencing one of the regions listed in Region and Endpoints in AWS General Reference.

Amazon EC2 instances and Auto Scaling groups that will be used in AWS CodeDeploy deployments must be launched and created in one of these regions.

If you're using the AWS CLI, run the aws configure command from the AWS CLI. Then you can view and set your default region.

If you're using the AWS CodeDeploy console, on the navigation bar, from the region selector, choose one of the supported regions.


To use services in the China (Beijing) Region or China (Ningxia) Region, you must have an account and credentials for those regions. Accounts and credentials for other AWS regions do not work for the Beijing and Ningxia Regions, and vice versa.

Information about some resources for the China Regions, such as AWS CodeDeploy Resource Kit bucket names and AWS CodeDeploy agent installation procedures, are not included in this edition of the AWS CodeDeploy User Guide.

For more information:

Required IAM roles are not available

If you rely on an IAM instance profile or a service role that was created as part of an AWS CloudFormation stack, if you delete the stack, all IAM roles are deleted, too. This may be why the IAM role is no longer displayed in the IAM console and AWS CodeDeploy no longer works as expected. To fix this problem, you must manually re-create the deleted IAM role.

Avoid concurrent deployments to the same Amazon EC2 instance

As a best practice, you should avoid situations that would result in more than one attempted deployment to an Amazon EC2 instance at the same time. In cases where commands from different deployments compete to run on a single instance, the deployments can time out and fail for the following reasons:

  • AWS CodeDeploy fails a deployment if its first lifecycle event doesn't start within five minutes of the triggering of the deployment. You can use the console or the AWS CLI create-deployment command to trigger a deployment.

  • AWS CodeDeploy fails a deployment if a lifecycle event does not start within five minutes of the end of the previous lifecycle event.

  • The AWS CodeDeploy agent can process only one deployment command at a time.

  • It's not possible to control the order in which deployments occur if more than one deployment attempts to run at the same time.


The default timeout for a script in a lifecycle event is 30 minutes. You can change the timeout to a different value in the AppSpec file. For more information, see Add an AppSpec File for an EC2/On-Premises Deployment.

AWS CodeDeploy logic considers a deployment to have failed if its steps are not complete within five minutes, even if a deployment process is otherwise running as expected. The five-minute limit can be exceeded if commands from multiple deployments are being sent to the AWS CodeDeploy agent at the same time.

For information about other challenges you might face with concurrent deployments in Auto Scaling groups, see Avoid associating multiple deployment groups with a single Auto Scaling group.

Using some text editors to create AppSpec files and shell scripts can cause deployments to fail

Some text editors introduce non-conforming, non-printing characters into files. If you use text editors to create or modify AppSpec files or shell script files to run on Amazon Linux, Ubuntu Server, or RHEL instances, then any deployments that rely on these files might fail. When AWS CodeDeploy uses these files during a deployment, the presence of these characters can lead to hard-to-troubleshoot AppSpec file validation failures and script execution failures.

In the AWS CodeDeploy console, on the event details page for the deployment, choose View logs. (Alternatively, you use the AWS CLI to call the get-deployment-instance command.) Look for errors like "invalid character," "command not found," or "file not found."

To address this issue, we recommend the following:

  • Do not use text editors that automatically introduce non-printing characters such as carriage returns (^M characters) into your AppSpec files and shell script files.

  • Use text editors that display non-printing characters such as carriage returns in your AppSpec files and shell script files, so you can find and remove any that may be automatically or randomly introduced. For examples of these types of text editors, search the Internet for "text editor show carriage returns."

  • Use text editors running on Amazon Linux, Ubuntu Server, or RHEL instances to create shell script files that run on Amazon Linux, Ubuntu Server, or RHEL instances. For examples of these types of text editors, search the Internet for "Linux shell script editor."

  • If you must use a text editor in Windows or Mac OS to create shell script files to run on Amazon Linux, Ubuntu Server, or RHEL instances, use a program or utility that converts text in Windows or Mac OS format to Unix format. For examples of these programs and utilities, search the Internet for "DOS to UNIX" or "Mac to UNIX." Be sure to test the converted shell script files on the target operating systems.

Using Finder in macOS to bundle an application revision can cause deployments to fail

Deployments might fail if you use the Finder graphical user interface (GUI) application on a Mac to bundle (zip) an AppSpec file and related files and scripts into an application revision archive (.zip) file. This is because Finder creates an intermediate __MACOSX folder in the .zip file and places component files into it. AWS CodeDeploy cannot find the component files, so the deployment fails.

To address this issue, we recommend you use the AWS CLI to call the push command, which zips the component files into the expected structure. Alternatively, you can use Terminal instead of the GUI to zip the component files. Terminal does not create an intermediate __MACOSX folder.