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

Troubleshoot Instance Issues

Tags must be set correctly

Use the list-deployment-instances command to confirm the instances used for a deployment are tagged correctly. If an Amazon EC2 instance is missing in the output, use the Amazon EC2 console to confirm the tags have been set on the instance. For more information, see Working with Tags in the Console in the Amazon EC2 User Guide for Linux Instances.

Note

If you tag an instance and immediately use AWS CodeDeploy to deploy an application to it, the instance might not be included in the deployment. This is because it can take several minutes before AWS CodeDeploy can read the tags . We recommend that you wait at least five minutes between the time you tag an instance and attempt to deploy to it.

AWS CodeDeploy agent must be installed and running on instances

To verify the AWS CodeDeploy agent is installed and running on an instance, see Verify the AWS CodeDeploy Agent Is Running.

To install, uninstall, or reinstall the AWS CodeDeploy agent, see Install or Reinstall the AWS CodeDeploy Agent.

Deployments do not fail for up to an hour when an instance is terminated during a deployment

AWS CodeDeploy provides a one-hour window for each deployment lifecycle event to run to completion. This provides ample time for long-running scripts.

If anything occurs that prevents scripts from running to completion while a lifecycle event is in progress (for example, if an instance is terminated or the AWS CodeDeploy agent is shut down), it might take up to an hour for the status of the deployment to be displayed as Failed. This is true even if the timeout period specified in the script is shorter than an hour. This is because when the instance is terminated, the AWS CodeDeploy agent will shut down and will be unable to process any additional scripts.

If an instance is terminated between lifecycle events or before the first lifecycle event step starts, however, the timeout occurs after just five minutes.

Analyzing log files to investigate deployment failures on instances

If the status of an instance in the deployment is anything other than Succeeded, you can review the deployment log file data to help identify the problem. For information about accessing deployment log data, see View Deployment Log Data.

Create a new AWS CodeDeploy log file if it was accidentally deleted

If you accidentally delete the deployment log file on an instance, AWS CodeDeploy does not create a replacement log file. To create a new log file, sign in to the instance, and then run these commands:

For an Amazon Linux, Ubuntu Server, or RHEL instance, run these commands in this order, one at a time:

Copy
sudo service codedeploy-agent stop
Copy
sudo service codedeploy-agent

For a Windows Server instance:

Copy
powershell.exe -Command Restart-Service -Name codedeployagent

Deployment or redeployment of the same files to the same instance locations fail with the error "File already exists at location"

If AWS CodeDeploy tries to copy files to an Amazon EC2 instance that already exists in the specified location, the deployment for that instance will fail, and you may see the error message "File already exists at location location-name."

If you try to redeploy files with the same names and locations, the redeployment will have a better chance of succeeding if you specify the application name and the deployment group with the same underlying deployment group ID you used before. AWS CodeDeploy uses the underlying deployment group ID to identify files to remove before a redeployment.

Deploying new files or redeploying the same files to the same locations on instances can fail for these reasons:

  • You specified a different application name for a redeployment of the same revision to the same instances. The redeployment will fail because even if the deployment group name is the same, the use of a different application name means a different underlying deployment group ID will be used.

  • You deleted and re-created a deployment group for an application and then tried to redeploy the same revision to the deployment group. The redeployment will fail because even if the deployment group name is the same, AWS CodeDeploy will reference a different underlying deployment group ID.

  • You deleted an application and deployment group in AWS CodeDeploy, then created a new application and deployment group with the same names as the ones you deleted. After that, you tried to redeploy a revision that had been deployed to the previous deployment group to the new one with the same name. The redeployment will fail because even though the application and deployment group names are the same, AWS CodeDeploy still references the ID of the deployment group you deleted.

  • You deployed a revision to a deployment group and then deployed the same revision to another deployment group to the same instances. The second deployment will fail because AWS CodeDeploy will reference a different underlying deployment group ID.

  • You deployed a revision to one deployment group and then deployed another revision to another deployment group to the same instances. There is at least one file with the same name and in the same location that the second deployment group tries to deploy. The second deployment will fail because AWS CodeDeploy will not remove the existing file before the second deployment starts. Both deployments will reference different deployment group IDs.

  • You deployed a revision in AWS CodeDeploy, but there is at least one file with the same name and in the same location. The deployment will fail because, by default, AWS CodeDeploy will not remove the existing file before the deployment starts.

To address these situations, do one of the following:

  • Remove the files from the locations and instances to which they were previously deployed, and then try the deployment again.

  • In your revision's AppSpec file, in either the ApplicationStop or BeforeInstall deployment lifecycle events, specify a custom script to delete files in any locations that match the files your revision is about to install.

  • Deploy or redeploy the files to locations or instances that were not part of previous deployments.

  • Before you delete an application or a deployment group, deploy a revision that contains an AppSpec file that specifies no files to copy to the instances. For the deployment, specify the application name and deployment group name that use the same underlying application and deployment group IDs as those you are about to delete. (You can use the get-deployment-group command to retrieve the deployment group ID.) AWS CodeDeploy will use the underlying deployment group ID and AppSpec file to remove all of the files it installed in the previous successful deployment.

Troubleshooting “InvalidSignatureException – Signature expired: [time] is now earlier than [time]” deployment errors

AWS CodeDeploy requires accurate time references in order to perform its operations. If your instance's date and time are not set correctly, they may not match the signature date of your deployment request, which AWS CodeDeploy will therefore reject.

To avoid deployment failures related to incorrect time settings, see the following topics: