2.1.4.7. Troubleshooting Deployment Issues
2.1.4.7. Troubleshooting Deployment Issues
When a CodeDeploy deployment fails, systematic debugging saves hours. Most failures fall into three categories: agent issues, permission issues, and hook script failures.
Step 1: Check the deployment status in the CodeDeploy console or CLI. The deployment event log shows which lifecycle hook failed and on which instance.
aws deploy get-deployment --deployment-id d-XXXXXXXXX
aws deploy list-deployment-instances --deployment-id d-XXXXXXXXX
Step 2: Check the agent logs on the failing instance:
- Agent communication:
/var/log/aws/codedeploy-agent/codedeploy-agent.log - Hook script output:
/opt/codedeploy-agent/deployment-root/<id>/logs/scripts.log
Common failure patterns:
| Symptom | Likely Cause | Fix |
|---|---|---|
| Deployment stuck at "Installing" | Agent not running or can't reach CodeDeploy | Verify agent status, check VPC endpoints |
DownloadBundle failure | S3 permission denied or KMS decrypt denied | Check instance profile + KMS key policy |
BeforeInstall hook timeout | Script hangs or takes too long | Check script logic, increase timeout in appspec |
| Health check failures after deploy | Application didn't start or wrong port | Check ValidateService hook, verify ALB target group |
| "Minimum healthy instances" error | Too many simultaneous failures | Reduce batch size or increase minimum healthy % |
Rollback configuration: Enable automatic rollback in the deployment group settings. Options: roll back on deployment failure, roll back on CloudWatch alarm breach, or both. Rollback redeploys the last known good revision.
Exam Trap: When CodeDeploy rolls back, it runs a new deployment of the previous revision — it doesn't "undo" the failed deployment. This means all lifecycle hooks run again. If your BeforeInstall hook can't handle being run twice (e.g., it creates a file that already exists), the rollback itself will fail.
