AWS Lambda Error - Handler not found: module.function_name
.jpeg)
A practical diagnostic guide for resolving Lambda handler import failures and misaligned deployment packages.
Problem
Your Lambda fires and immediately throws “Handler not found: module.function_name”. The function never enters your code, nothing runs, and CloudWatch shows only the handler error. This often follows renaming files, rearranging directories, changing build tooling, or deploying a new zip package.
{
"errorMessage": "Handler 'app.handler' missing on module 'app'",
"errorType": "Runtime.HandlerNotFound"
}
Clarifying the Issue
This is a packaging alignment problem. Lambda attempts to import the file and function referenced in your handler string, but the module is missing, nested incorrectly, cased differently, or doesn’t contain the function you declared. When the loader can’t find the entry point, Lambda aborts before executing your logic.
Why It Matters
A handler mismatch completely halts execution. No logs, no retries, no downstream actions. In production this resembles an outage because configuration looks correct but the runtime never starts your code. Fixing this quickly keeps MTTR low and avoids operational noise.
Key Terms
• Handler – The entry point Lambda calls.
• Module – The file that contains your handler function.
• Deployment package – The zip or container uploaded to Lambda.
• Runtime loader – The process that imports your handler at startup.
Steps at a Glance
- Check what handler Lambda is configured to use.
- Download the live deployment artifact.
- Download and inspect the zip structure.
- Verify your local code aligns with the handler.
- Confirm the handler is exported correctly.
- Rebuild the zip from a clean state.
- Redeploy the new artifact.
- Invoke the function to verify success.
Detailed Steps
Step 1: Check what handler Lambda is configured to use.
Start by confirming which handler Lambda thinks it should load. This validates the configuration half of the equation.
aws lambda get-function-configuration \
--function-name my-function \
--query 'Handler'
If the command returns "app.handler", that means Lambda expects a file named app.py or app.js with a function named handler.
With the configuration verified, your next step is to examine the actual deployment artifact running in AWS.
Step 2: Download the live deployment artifact.
Retrieve the URL to the deployed code so you can inspect what Lambda is currently executing.
aws lambda get-function \
--function-name my-function \
--query 'Code.Location' \
--output text > lambda-url.txt
This writes the signed S3 URL into lambda-url.txt.
Now that you have the download link, you can pull the production zip for inspection.
Step 3: Download and inspect the zip structure.
Use the retrieved URL to download the deployed package, then list its contents to check structure.
curl -L "$(cat lambda-url.txt)" -o current.zip
unzip -l current.zip
If you see a structure like:
Archive: current.zip
0 01-01-1980 00:00 project/
1234 01-01-1980 00:00 project/app.py
then the zip is incorrect — the folder was zipped instead of the contents.
Now that the artifact structure is clear, verify whether your local source aligns with the handler declaration.
Step 4: Verify your local code aligns with the handler.
Check your local project to confirm the module and function names match the handler exactly.
Handler app.handler requires:
• a file named app.py or app.js
• a function named handler inside that file
• matching casing
• file located at the root of the zip
If any of these differ, Lambda cannot import your code.
Once you confirm names and locations, check that the handler is actually exported.
Step 5: Confirm the handler is exported correctly.
Use quick local commands to ensure the handler is visible to the runtime.
Node.js:
node -e "console.log(require('./app.js'))"
If the output includes handler, it’s properly exported. If it returns {}, your handler is not exported.
Python:
python3 - << 'EOF'
import app
print(dir(app))
EOF
If handler appears, the module exposes it correctly.
Now that exports are validated, rebuild the zip so Lambda receives a clean package.
Step 6: Rebuild the zip from a clean state.
Rebuild the deployment package, ensuring you zip the contents of the project, not the project folder itself.
cd project
zip -r ../deploy.zip .
This produces a clean deploy.zip with top-level files.
With a correct package built, you’re ready to redeploy.
Step 7: Redeploy the new artifact.
Upload the corrected zip to Lambda.
aws lambda update-function-code \
--function-name my-function \
--zip-file fileb://deploy.zip
A successful response means Lambda has accepted the new code bundle.
With the new handler deployed, test a live invocation.
Step 8: Invoke the function to verify success.
Run a test invocation to confirm the handler now loads properly.
aws lambda invoke \
--function-name my-function \
--payload '{}' \
out.json
A StatusCode of 200 confirms the fix.
If you still see the handler error, alignment is still off somewhere and you should repeat the zip-structure analysis.
Pro Tips
Inspect build-tool output bundles.
Tools like SAM, Serverless Framework, and CDK may restructure directories. Always inspect the output folder, not your development tree.
Validate container COPY paths.
If using Lambda container images, ensure your Dockerfile COPY path places modules exactly where the handler expects them.
Always pull the live zip when debugging production.
Never assume your local filesystem matches what is deployed. Production-level debugging requires analyzing the actual deployed artifact.
Conclusion
This issue always comes down to handler alignment. The handler string must point to a real file at the root of the deployment package, containing a real function with the exact name and casing. Once corrected, Lambda initializes cleanly, the runtime loader finds your module, and your code executes without friction.
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