General troubleshooting issues
Topics
- General troubleshooting checklist
- CodeDeploy deployment resources are supported in only in some Amazon Regions
- Procedures in this guide do not match the CodeDeploy console
- Required IAM roles are not available
- Using some text editors to create AppSpec files and shell scripts can cause deployments to fail
- Using Finder in macOS to bundle an application revision can cause deployments to fail
General troubleshooting checklist
You can use the following checklist to troubleshoot a failed deployment.
-
See View CodeDeploy deployment details and View Instance Details to determine why the deployment failed. If you cannot determine the cause, review the items in this checklist.
-
Check that you have correctly configured the instances:
-
Was the instance launched with an EC2 key pair specified? For more information, see EC2 Key Pairs in Amazon EC2 User Guide.
-
Is the correct IAM instance profile attached to the instance? For more information, see Configure an Amazon EC2 instance to work with CodeDeploy and Step 4: Create an IAM instance profile for your Amazon EC2 instances.
-
Was the instance tagged? For more information, see Working with tags in the console in Amazon EC2 User Guide.
-
Is the CodeDeploy agent installed, updated, and running on the instance? For more information, see Managing CodeDeploy agent operations. To check which version of the agent is installed, see Determine the version of the CodeDeploy agent.
-
-
Check the application and deployment group settings:
-
To check your application settings, see View application details with CodeDeploy.
-
To check your deployment group settings, see View deployment group details with CodeDeploy.
-
-
Confirm the application revision is correctly configured:
-
Check the format of your AppSpec file. For more information, see Add an application specification file to a revision for CodeDeploy and CodeDeploy AppSpec file reference.
-
Check your Amazon S3 bucket or GitHub repository to verify your application revision is in the expected location.
-
Review the details of your CodeDeploy application revision to ensure that it is registered correctly. For information, see View application revision details with CodeDeploy.
-
If you're deploying from Amazon S3, check your Amazon S3 bucket to verify CodeDeploy has been granted permissions to download the application revision. For information about bucket policies, see Deployment prerequisites.
-
If you're deploying from GitHub, check your GitHub repository to verify CodeDeploy has been granted permissions to download the application revision. For more information, see Create a deployment with CodeDeploy and GitHub authentication with applications in CodeDeploy.
-
-
Check that the service role is correctly configured. For information, see Step 2: Create a service role for CodeDeploy.
-
Confirm you followed the steps in Getting started with CodeDeploy to:
-
Provisioned a user with the appropriate permissions.
-
Install or upgrade and configure the Amazon CLI.
-
Create an IAM instance profile and a service role.
For more information, see Identity and access management for Amazon CodeDeploy.
-
-
Confirm you are using Amazon 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.
CodeDeploy deployment resources are supported in only in some Amazon Regions
If you do not see or cannot access applications, deployment groups, instances, or other deployment resources from the Amazon CLI or the CodeDeploy console, make sure you're referencing one of the Amazon Regions listed in Region and endpoints in Amazon Web Services General Reference.
EC2 instances and Amazon EC2 Auto Scaling groups that are used in CodeDeploy deployments must be launched and created in one of these Amazon Regions.
If you're using the Amazon CLI, run the aws configure command from the Amazon CLI. Then you can view and set your default Amazon Region.
If you're using the CodeDeploy console, on the navigation bar, from the region selector, choose one of the supported Amazon Regions.
Important
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 Amazon regions do not work for the Beijing and Ningxia Regions, and vice versa.
Information about some resources for the China Regions, such as CodeDeploy Resource Kit bucket names and CodeDeploy agent installation procedures, are not included in this edition of the CodeDeploy User Guide.
For more information:
-
CodeDeploy in Getting Started with Amazon in the China (Beijing) Region
-
CodeDeploy User Guide for the China Regions (English version | Chinese version)
Procedures in this guide do not match the CodeDeploy console
The procedures in this guide are written to reflect the new console design. If you are using the older version of the console, many of the concepts and basic procedures in this guide still apply. To access help in the new console, choose the information icon.
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 Amazon 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 CodeDeploy no longer works as expected. To fix this problem, you must manually re-create the deleted IAM role.
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 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 CodeDeploy console, on the event details page for the deployment, choose
View logs. (Or you use the Amazon 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 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 might be introduced. For examples of these types of text editors, search the internet for text editors that 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 editors.
-
If you must use a text editor in Windows or macOS 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 macOS 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.
CodeDeploy cannot find the component files, so the deployment fails.
To address this issue, we recommend you use the Amazon 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.