AWS Lambda Error - Unable to import module 'xyz'
.jpeg)
A fast, field-tested playbook for diagnosing and fixing missing modules in AWS Lambda
Problem
Your Lambda deploys successfully but fails at runtime with the error “Unable to import module 'xyz'”. The function never enters your handler, your code does not execute, and CloudWatch logs show only the import failure. This typically happens when required files, modules, or dependencies are missing from the deployment package or placed in incorrect directory paths.
{
"errorMessage": "Unable to import module 'app': No module named 'requests'",
"errorType": "Runtime.ImportModuleError"
}
Clarifying the Issue
This error means the Lambda runtime couldn’t import a module referenced in your code. The missing module may be part of your own project files, a dependency you forgot to package, or an external library that must be included manually because Lambda doesn’t supply it by default. If the file path, folder structure, or dependency layer is incorrect, Lambda’s loader will fail before your handler is invoked.
Why It Matters
An import failure stops the runtime cold. Nothing executes, retries won't help, and downstream systems never receive events. When this happens in production, it creates a silent outage: the function appears deployed and healthy but can’t run its logic. Fixing this quickly restores functionality and prevents cascading failures.
Key Terms
- Module – A Python or Node.js file or library required by your code.
- Dependency – An external library your Lambda function uses.
- Deployment package – The zip or container image uploaded to Lambda.
- Import loader – The process that locates modules inside the execution environment.
Steps at a Glance
- Review the CloudWatch error to identify the missing module.
- Check that your project files include the module locally.
- Confirm the module exists in the deployed Lambda zip.
- Package dependencies correctly for the Lambda runtime.
- Rebuild dependencies using the correct Lambda architecture.
- Rebuild the deployment package with modules at the root.
- Redeploy the package to Lambda.
- Invoke the function to confirm the fix.
Detailed Steps
Step 1: Review the CloudWatch error to identify the missing module.
Start by inspecting CloudWatch logs to see exactly which module is missing. Lambda tells you the precise module name it failed to load.
aws logs tail /aws/lambda/my-function --since 5m
If you see a message such as No module named 'requests', that module is missing from your deployment package.
Now that you know what failed to import, verify that it exists locally.
Step 2: Check that your project files include the module locally.
Search your project to ensure the module is referenced correctly and present in your environment.
grep -R "import requests" .
If the library isn’t installed locally, it won’t be in your zip either.
With local presence confirmed, inspect the deployed artifact.
Step 3: Confirm the module exists in the deployed Lambda zip.
Download and inspect the deployed zip file to confirm whether the missing module is included.
aws lambda get-function \
--function-name my-function \
--query 'Code.Location' \
--output text > lambda-url.txt
curl -L "$(cat lambda-url.txt)" -o current.zip
unzip -l current.zip | grep requests
If the module is not found here, it was not packaged.
Now that you've identified a packaging gap, properly package dependencies for Lambda.
Step 4: Package dependencies correctly for the Lambda runtime.
Install dependencies into your project directory so they can be included in the deployment zip.
For Python (single dependency):
pip install requests -t .
For Python (multiple dependencies, best practice):
pip install -r requirements.txt -t .
For Node.js:
npm install axios
If dependencies now appear in your project directory, proceed to architecture validation.
Step 5: Rebuild dependencies using the correct Lambda architecture.
Lambda runs on Linux, so Python wheels built on macOS or Windows may not work. Rebuild dependencies inside a Lambda-compatible environment.
docker run -v "$PWD":/var/task \
public.ecr.aws/lambda/python:3.11 \
pip install -r requirements.txt -t /var/task
This ensures all dependencies are compiled for the correct architecture.
Once dependencies are architecture-safe, rebuild the deployment package.
Step 6: Rebuild the deployment package with modules at the root.
Zip your function files and dependencies together. All modules and folders must sit at the root of the zip file.
zip -r deploy.zip .
A correct zip contains directories like requests/, urllib3/, or node_modules/ at the top level.
With a valid deployment package built, redeploy it to Lambda.
Step 7: Redeploy the new artifact.
Upload the corrected package.
aws lambda update-function-code \
--function-name my-function \
--zip-file fileb://deploy.zip
A successful update means Lambda now has the corrected code bundle.
Next, validate the import process with a live invocation.
Step 8: Invoke the function to confirm the fix.
Run a test event to verify that the import now succeeds.
aws lambda invoke \
--function-name my-function \
--payload '{}' \
out.json
If the result includes "StatusCode": 200, the fix is successful.
If the import error persists, repeat the packaging and dependency architecture checks.
Pro Tips
Test with minimal payloads.
Simple test events reduce variables and help you isolate import-related issues.
Consider moving heavy dependencies into Lambda Layers.
Layers reduce deployment package size and simplify dependency management.
Always package dependencies on Linux.
Lambda does not run macOS or Windows binaries, and Python wheels must be Linux-compatible.
Conclusion
This error always points to missing or incorrectly packaged modules. Ensure your dependencies are included, built for the correct architecture, and located at the root of the deployment package. Once aligned, Lambda will import modules correctly and your code will execute without interruption.
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