AWS Lambda Error – Cannot find module 'aws-sdk'
.jpeg)
By checking the runtime, verifying artifact structure, and bundling dependencies correctly, you can eliminate this class of errors entirely and restore clean startup behavior
Problem
Your Lambda attempts to import or require aws-sdk (or any library), but fails immediately with:
Error: Cannot find module 'aws-sdk'
or in Python-style Node bundlers:
Runtime.ImportModuleError: Error: Cannot find module 'aws-sdk'
The code never executes — the runtime cannot load the dependency at startup.
- Dependency not bundled into the deployment artifact
- Incorrect zip/package structure
- Using a custom runtime or Docker image missing the library
Clarifying the Issue
Lambda resolves dependencies directly from inside your deployment package. Older Node.js runtimes bundled the AWS SDK v2, but newer runtimes — especially Node.js 18+ — no longer include the AWS SDK.
If the dependency isn’t packaged or is placed in the wrong directory, the import fails immediately.
- Node.js 18+ requires bundling your own SDK or using AWS SDK v3
- Build tools can tree-shake or omit modules
- Zip structure may unintentionally nest your dependencies
Why It Matters
Missing dependencies block execution before your handler even runs, halting all business logic.
- No retries
- No meaningful logs
- No ability to debug your actual code
This issue completely prevents the function from starting.
Key Terms
- Dependency bundling – Packaging modules into the Lambda artifact
- Layer – A separate package used to provide shared dependencies
- Tree-shaking – Build optimization that removes unused imports
Steps at a Glance
- Confirm the import error in CloudWatch
- Check the runtime version for AWS SDK availability
- Inspect the deployed zip for the
node_modulesfolder - Validate the zip folder structure
- Reinstall dependencies for Linux
- Bundle dependencies correctly
- Re-deploy the updated package
- Test with a clean manual invocation
Detailed Steps
Step 1: Confirm the import error in CloudWatch.
To verify that the failure is due to dependency resolution, pull recent logs:
aws logs tail /aws/lambda/my-function --since 5m
You should see the familiar:
Error: Cannot find module 'aws-sdk'
This confirms the import failed at startup. Now check your runtime configuration.
Step 2: Check the runtime version for AWS SDK availability.
To determine whether your runtime bundles the AWS SDK, retrieve its configuration:
aws lambda get-function-configuration \
--function-name my-function \
--query 'Runtime'
If the runtime is Node.js 18 or newer, the SDK is not included — you must package it yourself. Next, check whether it exists in the deployed artifact.
Step 3: Inspect the deployed zip for node_modules.
To see what Lambda actually received, download the live artifact and inspect its contents:
aws lambda get-function \
--function-name my-function \
--query 'Code.Location' \
--output text > lambda_url.txt
curl -L "$(cat lambda_url.txt)" -o deployed.zip
unzip -l deployed.zip | grep aws-sdk
If the search returns nothing, the dependency never made it into the zip. Now confirm that the folder structure itself is correct.
Step 4: Validate the zip folder structure.
To confirm that your modules are placed where Lambda expects, inspect for nested directories:
Common incorrect structure:
Archive: deployed.zip
/project/node_modules/aws-sdk/...
Correct structure:
Archive: deployed.zip
node_modules/aws-sdk/...
index.js
If your modules are nested, Lambda will never find them. Next, ensure you installed them for the correct OS/architecture.
Step 5: Reinstall dependencies for Linux (x86/ARM).
If you develop on macOS/Windows, native modules must be rebuilt for Linux. Use Docker to recreate the correct environment:
docker run -v "$PWD":/var/task \
node:18 \
bash -c "npm install"
This ensures your deployment folder contains Linux-compatible modules. Now rebuild the artifact properly.
Step 6: Bundle dependencies correctly.
To create a clean deployment artifact with correct directory structure, repackage the contents:
zip -r deploy.zip .
This produces a flat directory layout with your handler file and node_modules side-by-side at the root. Now redeploy the package.
Step 7: Re-deploy the updated package.
To update Lambda’s code with your corrected artifact, run:
aws lambda update-function-code \
--function-name my-function \
--zip-file fileb://deploy.zip
After deployment completes, verify the fix by invoking the function manually.
Step 8: Test with a clean manual invocation.
To confirm that Lambda now loads the dependency correctly, invoke it directly:
aws lambda invoke \
--function-name my-function \
--payload '{}' \
out.json
Check CloudWatch for any remaining import errors. If none remain, your dependency is now loading successfully.
Pro Tips
- Use AWS SDK v3 with Node.js 18+
- Use Lambda layers for large dependency sets
- Always confirm artifact structure before deploying
Conclusion
“Cannot find module 'aws-sdk'” occurs when Lambda cannot load dependencies due to missing modules, incompatible runtime assumptions, or incorrect packaging. By checking the runtime, verifying artifact structure, and bundling dependencies correctly, you can eliminate this class of errors entirely and restore clean startup behavior.
Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.
Comments
Post a Comment