You're staring at CloudWatch, and there it is: Task timed out after 3.00 seconds. Your Lambda function kicked off, did something, and then got killed by the runtime. No stack trace, no error thrown from your code. Just a timeout. This is the single most common Lambda issue I see, and 9 times out of 10, it's not a bug in your logic. It's a configuration or environmental issue. Let's walk through this. Start at the top, stop when it works.
Step 1: The 30-Second Fix – Bump the Timeout (and check the obvious)
Yeah, I know. It sounds like cheating. But you'd be surprised how many people leave the default 3-second timeout on a function that calls an external API. The default is 3 seconds for a reason: it forces you to think. But if your function legitimately needs more time, just increase it.
Go to the Lambda console. Find your function. Configuration tab. General configuration. Edit. Change the timeout from 3 seconds to something realistic. For most API calls, 10-15 seconds is plenty. For batch jobs, maybe 30. Don't go crazy; you're paying for that time.
While you're there, check the memory. Lambda allocates CPU proportionally to memory. 128 MB gives you a sliver of a CPU core. If you're doing anything CPU-bound, bump memory to 512 MB or 1024 MB. You might be surprised how much faster your code runs, and the timeout goes away.
If that didn't fix it, move on. This was just the warm-up.
Step 2: The 5-Minute Fix – Look at What Your Function Is Actually Waiting On
Okay, so you bumped the timeout to 30 seconds and it still times out? That means your function is stuck waiting on something. The usual suspects: a database connection, an HTTP call to a slow service, or a VPC networking issue.
Is your Lambda in a VPC?
If your Lambda is attached to a VPC, and it needs to reach the internet (e.g., to call an external API), it needs a NAT Gateway. Without one, your function will hang trying to connect until it times out. This is a classic. I've seen entire teams burn a day on this.
Check: Does your Lambda's subnet have a route to a NAT Gateway? If not, either add one or move the function out of the VPC if it doesn't need VPC resources.
Are you using the AWS SDK with default retries?
The AWS SDK for JavaScript, Python, etc., has built-in retries. If you're calling another AWS service (like DynamoDB) and it's throttling, the SDK will retry with exponential backoff. That can easily eat up your timeout. Check your CloudWatch logs for retry attempts. You might see something like Retrying request or ThrottlingException before the timeout.
Fix: Increase the timeout further, or better, handle the throttling by adjusting your read/write capacity or using adaptive retries. Also, set a lower maxRetries in your SDK client config if you want to fail fast.
What about cold starts?
If your function is timing out only on the first invocation after a period of inactivity, it's a cold start. The runtime has to initialize, load your code, and establish connections. For Java or .NET, this can take several seconds. If your timeout is 3 seconds, you're dead on arrival.
Quick check: Look at the Init Duration in your CloudWatch logs. If it's over 1 second, cold starts are your problem. Solutions: increase timeout, use Provisioned Concurrency (costs money), or switch to a lighter runtime like Python or Node.js.
If none of this applies, your code itself is slow. That's the advanced section.
Step 3: The 15+ Minute Fix – Profile and Optimize Your Code
So you've increased the timeout, checked VPC and cold starts, and it still times out. Now you need to find out where your code is spending its time. This is where you roll up your sleeves.
Enable AWS X-Ray
X-Ray is your best friend here. It traces requests through your Lambda and downstream services. Turn it on: in the Lambda console, go to Configuration > Monitoring and operations tools > Edit, and enable Active tracing. Then redeploy. After a few invocations, go to the X-Ray console and look at the trace map. You'll see exactly which segment is taking the longest. Maybe it's a DynamoDB call, maybe it's an external HTTP request, maybe it's your own code.
Add timing logs (old school but effective)
If you don't want to use X-Ray, just add console.log statements with timestamps around suspicious blocks. For example:
const start = Date.now();
await someSlowOperation();
console.log(`someSlowOperation took ${Date.now() - start} ms`);
Do this for each major step. The logs will show you the culprit.
Common culprits
- Inefficient database queries: Missing indexes, full table scans. Use
EXPLAINin your database. - Large payloads: Downloading a 100 MB file from S3 into memory before processing. Stream it instead.
- Synchronous calls to slow APIs: If you're calling a third-party API that takes 5 seconds, your Lambda will wait. Use asynchronous patterns or increase timeout.
- Recursive functions: Accidental infinite loops. Add a counter and bail out.
- Memory leaks: Not usually a problem with short-lived Lambdas, but if you're reusing global variables, they can grow. Check your code.
Optimize dependencies
If you're using Java, the cold start is brutal. Consider using GraalVM native images or switching to a lighter runtime. For Node.js, make sure you're not importing huge libraries like aws-sdk v2 (use v3 which is modular). For Python, avoid importing heavy modules like pandas unless you absolutely need them; they add to init time.
Test locally with SAM or Serverless Framework
Use sam local invoke or sls invoke local to run your function locally with a debugger. You can step through the code and see where it hangs. This is often faster than deploying and waiting for logs.
When to give up and re-architect
If your function consistently needs more than 15 minutes, Lambda is the wrong tool. The maximum timeout is 15 minutes. If you're hitting that, you should be using Step Functions, ECS, or Fargate. Don't try to shoehorn a long-running process into Lambda. It's not designed for it.
That's the flow. Start at the top, work your way down. Most of the time, you'll fix it in step 1 or 2. If you're in step 3, grab a coffee and fire up X-Ray. You'll find it.