Topic lessonTopic: Lambda and API Gateway: inputs, testing and failure investigation
Troubleshoot AWS Lambda timeouts: duration, dependency waits and retries
A Lambda timeout means the function did not finish within its configured deadline; it does not identify the cause. Establish the invocation method and which deadline expired, then investigate input size, downstream waits and function work. Check results and side effects before extending the deadline or invoking again.
Choose the next check from the observed symptom, distinguish caller/function deadlines and retries, and avoid unsupported replays or setting changes.
Know events, handlers, returns and logs. This guide focuses on Event Functions in the default execution environment. No AWS account is needed; paste no real logs, and create or reconfigure no functions.
First establish which deadline expired
| Observation | What it does not establish | Next check |
|---|---|---|
| Caller connection times out | The function stopped or made no changes | Outcome of that request and both deadlines |
| A function timeout is recorded | Networking was the sole cause | Inputs and work/wait stages |
| Synchronous Invoke is 200 with a function error | The intended work succeeded | FunctionError and returned result/error |
| Asynchronous Invoke is 202 | Completed function outcome | Execution outcome and retry/failure records |
Separate the deadline from work duration
The deadline is a configured limit; duration is time actually spent on the work. Ordinary functions covered here use 1–900 seconds, with a 3-second default. Input and dependency variability matter; a limit close to an average duration may leave insufficient margin.
- Fixed example → Deadline: 5 sAllowed time
- Fixed example → Stipulated work: 8 sAssumed work requirement
- Fixed example
- Assume synchronous invocation; compare two supplied durations.
- Deadline: 5 s
- Allowed time; the model expires before completion.
- Stipulated work: 8 s
- Assumed required work, not an observed completion.
| Stipulated work | Deadline | Fixed-model outcome |
|---|---|---|
| 8 seconds | 3 seconds | Timeout: stipulated work exceeds the deadline |
| 8 seconds | 5 seconds | Timeout: stipulated work exceeds the deadline |
| 8 seconds | 10 seconds | Completed: stipulated work is shorter than the deadline |
Investigate inputs, waits and work from evidence
- Record the function/version or alias, time and invocation method: synchronous, asynchronous or event source mapping.
- Correlate the returned result/error and logs for that request. An API 200 or 202 alone is insufficient.
- Compare recent changes, input size/count and time spent waiting on dependencies. A small successful test does not establish large-input behavior.
- Select a candidate supported by observations. Compare before/after under controlled conditions and verify output and duplicate side effects.
| Clue | Check | Avoid |
|---|---|---|
| Only larger inputs are slow | Count, size, values and amount of work | Declaring health from one small sample |
| A wait follows a downstream call | Response, destination and dependency deadline | Treating every timeout as a security-group issue |
| Compute or memory pressure is suspected | Work stages, usage and configuration | Predicting half the time from twice the memory |
| Logs are not visible | Time/function/log destination, permissions and delay | Concluding the function never ran |
Memory configuration also affects allocated CPU, but its effect depends on the work. For VPC-connected functions, investigate routing, traffic controls and name resolution. Match changes to the symptom; opening all permissions or adding NAT indiscriminately is not a diagnostic method.
Worked example: a deadline while awaiting a dependency
mode = synchronous
function_deadline = 5 seconds
input = fixed sample
last_observed_stage = downstream request started
function_result = timeout
root_cause = not establishedThe notes establish a function timeout and the last observed stage: a downstream call. They do not establish a slow dependency, failed connection or unfinished later work. Next inspect the destination, response/error and time interval, and compare with a prior successful case.
A deadline increase is an option after establishing required work and bounded waits. After a change, verify the intended result, duration variability, downstream load and cost implications, rather than only the absence of a timeout. This page explains diagnostic choices and performs no live change.
Before replaying, identify who owns retries
| Mode | Distinction | Inspect |
|---|---|---|
| Direct synchronous invocation | Lambda does not automatically retry function errors; caller/SDK retries differ | Function result, caller configuration and replay history |
| Asynchronous invocation | Default two extra function-error attempts; configurable 0–2. Throttling differs | Execution, event age, failed-event destination and duplicates |
| Queue/stream event source mapping | Source-specific rules; do not reuse the 0–2 setting | Source configuration and batch/record handling |
Idempotency means designing repeated-event handling to avoid effects such as duplicate orders. For example, a repeated order ID should not create a second completed order. An implementation must also address concurrency, partial failure and record retention; an in-memory ID list alone does not establish correctness.
Choose the next check from the symptom
Choose an option to see the result and explanation.
Choose an option to see the result and explanation.
Choose an option to see the result and explanation.
Choose an option to see the result and explanation.
Choose an option to see the result and explanation.
Choose an option to see the result and explanation.
Check, then explain in your own words
- Identify the invocation method and expired deadline.
- Separate evidence for inputs, dependency waits and work.
- Change the fixed lab deadline and explain what remains unverified in reality.
Check your understanding: What should you establish before increasing a deadline?
Establish invocation mode, which deadline expired, inputs, work/wait observations, existing results and replay side effects.
Timeout is a symptom rather than an established cause; no response is not evidence that no change occurred.
Sources and conditions checked
The official references used in this lesson are collected here with their scope, conditions and corresponding sections. Independent expert review and live AWS comparison have not been performed.
Scope and conditionsSeparate synchronous return values, function errors/logs and caller connection deadlines. Synthetic logs are neither retrieved logs nor a complete runtime log format.
Used in this lessonFirst establish which deadline expired Choose the next check from the symptom
Scope and conditionsDistinguish 200 for RequestResponse from 202 for Event. Status codes do not replace function-error inspection. The model assumes acceptance/permissions and sends no API request.
Used in this lessonFirst establish which deadline expired
Scope and conditionsThe ordinary function deadline is 1–900s; special Managed Instances modes are outside this model. Duration is stipulated, not inferred from memory. Deadline equality follows a local teaching rule.
Used in this lessonSeparate the deadline from work duration Investigate inputs, waits and work from evidence Worked example: a deadline while awaiting a dependency
Scope and conditionsRetry ownership and conditions depend on invocation method/error type. Direct synchronous function errors are not automatically retried by Lambda; stream/queue mappings have distinct rules.
Used in this lessonFirst establish which deadline expired Investigate inputs, waits and work from evidence Before replaying, identify who owns retries Choose the next check from the symptom
Scope and conditionsDistinguish the default two additional function-error attempts from throttling/system-error handling. Duplicate delivery can occur even without function errors; 1+n is not a guaranteed actual count.
Used in this lessonFirst establish which deadline expired Before replaying, identify who owns retries Choose the next check from the symptom
Scope and conditionsMaximumRetryAttempts 0–2 configures function-error retries. Event age/discard/failure destinations are separate. Valid configuration does not prove execution success. No real setting is changed.
Used in this lessonBefore replaying, identify who owns retries Choose the next check from the symptom
Scope and conditionsReal log delivery requires execution-role permissions and may be delayed. Returns and logs differ; fixed synthetic log examples do not establish actual log arrival.
Used in this lessonInvestigate inputs, waits and work from evidence
Scope and conditionsDistinguish initialization, handler and response stages; investigate event contracts and downstream waits. Valid JSON does not establish handler-specific value validity. Observation notes are fictional, not retrieved logs.
Used in this lessonInvestigate inputs, waits and work from evidence
Scope and conditionsMemory configuration also affects allocated CPU. Effects depend on work, waits and inputs; a setting alone does not predict duration. No live configuration change or load test was performed.
Used in this lessonInvestigate inputs, waits and work from evidence
Scope and conditionsInvestigate routing, controls and name resolution for VPC-connected functions. Timeout alone does not establish a networking failure; neither open-all rules nor unconditional NAT deployment is prescribed.
Used in this lessonInvestigate inputs, waits and work from evidence
Scope and conditionsRefer to idempotent duplicate handling and performance tests covering inputs/dependencies. The order example explains the concept; it implements no persistence, concurrency control or retention policy and promises no exactly-once delivery.
Used in this lessonWorked example: a deadline while awaiting a dependency Before replaying, identify who owns retries