Troubleshooting and Optimization · Topic 3 of 5

Debugging Code, Integrations and Deployment Failures

Find the cause of Lambda, API Gateway and SDK errors, read CloudFormation, CodeDeploy and CodeBuild failure output, and use AI tools to diagnose errors.

5 min

In a nutshell

4xx means fix the request or permission; 5xx and throttling are retried with backoff.
502 from Lambda proxy usually means a bad response shape; 504 means the integration timeout.
The first failed event in a CloudFormation stack holds the real cause.

What it is

Troubleshooting means working from a symptom, such as an HTTP error, a timeout or a failed deployment, to a cause that you can fix. The exam gives you the symptom and often one log line.

Most problems are permissions, configuration, limits or code defects.

How it works

Reading error signatures

Errors in the 4xx range mean the request was wrong or not allowed, and retrying will not help. Errors in the 5xx range, and throttling errors, are often temporary, so the AWS SDKs retry them with exponential backoff and jitter.

Signature	Usual cause
AccessDeniedException or 403	Missing or denied permission; check the identity policy, resource policy and any explicit deny
ThrottlingException, 429, ProvisionedThroughputExceededException	A rate or capacity limit was hit; back off, then raise capacity or concurrency
ValidationException or 400	The request parameters are malformed
Task timed out after N seconds	The function ran past its timeout; raise it (maximum 900 seconds) or fix the slow call
Runtime.HandlerNotFound	The handler setting does not match the code file and function name
Max Memory Used equals Memory Size, or the runtime is killed	Out of memory; raise memory or fix the leak

API Gateway with Lambda

Response	Meaning
502 Bad Gateway	The Lambda function returned a response in the wrong shape. For proxy integration it must return statusCode, headers and a body that is a string.
504 Gateway Timeout	The integration took longer than the integration timeout, 29 seconds by default for REST APIs
500 Internal Server Error	Often a permissions problem: API Gateway is not allowed to invoke the function
403 Forbidden	Authorizer, API key or resource policy rejected the call
429 Too Many Requests	Throttling at the stage or account level

Turn on execution logging on the stage to see how API Gateway processed the request. Both execution and access logging need an IAM role that lets API Gateway write to CloudWatch Logs.

Lambda in a VPC

A function attached to a VPC has no internet access by default. Calls to AWS services time out unless the subnet has a route to a NAT gateway or the VPC has an interface or gateway endpoint for the service.

Tools for the developer

AWS SAM CLI: sam local invoke -e event.json runs a function locally with a test event, and sam logs reads its logs.
CloudTrail: records the denied API call, including the principal and action.

Troubleshooting deployment failures

Deployment tools name the failing step in their output.

Tool	Where to look
CloudFormation	The stack events list. Find the first resource with a failed status; its status reason is the real error, and later resources only show cancelled.
CodeBuild	Phase details show which phase failed (for example INSTALL, PRE_BUILD or BUILD). Full output is in CloudWatch Logs or S3 if you configured them. Check buildspec.yml and the service role.
CodeDeploy on EC2	The deployment page lists each lifecycle event. Agent logs are in /var/log/aws/codedeploy-agent/ and script output in the deployment-logs folder under /opt/codedeploy-agent/.

Useful specifics:

A CloudFormation stack that fails on creation ends in ROLLBACK_COMPLETE and cannot be updated, so delete it and create it again. A stack in UPDATE_ROLLBACK_FAILED can use ContinueUpdateRollback after you fix the blocking resource.
CodeDeploy EC2 hooks run in order: ApplicationStop, DownloadBundle, BeforeInstall, Install, AfterInstall, ApplicationStart, ValidateService. A script that exits with a nonzero code fails the deployment.

AI tools for troubleshooting

Diagnose with Amazon Q: when the console shows an error from Lambda, Amazon ECS, Amazon S3, Amazon EC2 or Step Functions, a button lets Amazon Q Developer explain the error and list steps to resolve it. It also covers IAM permission errors across console pages.
CloudWatch investigations: a generative AI assistant that scans metrics, logs, deployment events and X-Ray data and proposes findings and root cause hypotheses for an alarm or issue.
Chat in your IDE: Kiro can explain a stack trace and suggest a fix. The Amazon Q Developer IDE plugins do this too until AWS discontinues them on April 30, 2027.

Treat every suggestion as a hypothesis. Check it against the logs and the permissions the tool actually used.

How the exam asks about this

"API Gateway returns 502 for a Lambda proxy integration, and the function logs show success" -> the function returned a malformed proxy response, such as a body that is not a string.
"A CodeDeploy deployment fails at ApplicationStart" -> read the deployment lifecycle event output and the script log on the instance, then fix the start script.
"A function in a private subnet times out calling DynamoDB" -> add a VPC gateway endpoint for DynamoDB, or a NAT gateway.

What to remember for the exam

4xx means fix the request or permission; 5xx and throttling are retried with backoff.
502 from Lambda proxy usually means a bad response shape; 504 means the integration timeout.
The first failed event in a CloudFormation stack holds the real cause.
A stack in ROLLBACK_COMPLETE after a failed create must be deleted.
CodeBuild phase details show which phase failed; buildspec.yml defines them.
Diagnose with Amazon Q explains console errors, but does not replace logs.

Watch out

Do not raise a timeout or memory setting before reading the logs. A function waiting on an unreachable endpoint will simply wait longer.

Common mistakes

Reading the last CloudFormation event. The last events are usually cancellations. Scroll to the earliest failure.

Retrying a 403. Retries cannot fix a permission problem. Read the denied action in CloudTrail and correct the policy.

Blaming code for a network timeout. A VPC function with no route out looks like slow code.

Check yourself

What does a 504 from API Gateway mean?
The integration did not answer within the integration timeout, which is 29 seconds by default for REST APIs.
Where is the real cause of a failed stack update?
In the earliest resource event with a failed status, whose status reason names the error.
What does the Diagnose with Amazon Q button do?
It has Amazon Q Developer explain a console error and suggest resolution steps.

Topic 3 of 5 in Troubleshooting and Optimization

Test yourself on Troubleshooting and Optimization

The full AWS DVA-C03 question bank has 850 questions, with timed practice exams and an explanation for every answer.

Get Full Access Try Sample Exam

This study guide is independent and is not affiliated with, endorsed by, or sponsored by AWS. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.