AWS Lambda Error – Cannot find module './index'

#aws#lambda#devops#cloud

A practical diagnostic guide for fixing Lambda handler file resolution failures caused by missing files, wrong extensions, or nested zip structures.

Problem

Your Lambda deploys successfully, but immediately fails on invocation with:

Error: Cannot find module './index'

This happens before your code runs — the runtime cannot locate the handler file at all.

Three common causes:

• File is missing or named incorrectly
• Zip structure nests the file inside a folder
• Runtime expects a different extension than what you provided

---

Clarifying the Issue

Lambda must find the module file (index.js, index.mjs, index.py, etc.) at the root of the deployment package. If the file is absent, misnamed, cased differently, or inside a folder, the runtime aborts before loading your function.

Key misunderstandings:

• Runtime dictates the required file extension
• Zip nesting causes the handler to become invisible
• Local structure ≠ deployed structure

---

Why It Matters

Lambda cannot execute anything until the handler file loads. Every request instantly fails, producing timeouts, retries, or downstream errors.

Impact of a missing module:

• Zero code execution
• Full request failure
• Pipeline stalls or repeated retries

---

Key Terms

• Handler – The module + exported function Lambda must load (example: index.handler).
• Module file – The actual file that must exist at zip root (index.js, index.py).
• Deployment package – The zip uploaded to Lambda, must contain code at the top level.

---

Steps at a Glance

1. Confirm the module error in CloudWatch
2. Check runtime for required extension
3. Inspect the zip structure
4. Verify handler matches file name exactly
5. Rebuild a flat zip from the project root
6. Deploy and retest

---

Detailed Steps

Step 1: Confirm the module error in CloudWatch.

Pull logs to verify the runtime couldn’t load the handler:

aws logs tail /aws/lambda/my-function --since 5m

You should see:

Error: Cannot find module './index'

This confirms a module resolution failure — move on to runtime verification.

---

Step 2: Check the runtime for required extension.

Different runtimes expect different module filenames. Retrieve the runtime:

aws lambda get-function-configuration \
  --function-name my-function \
  --query 'Runtime'

Match your file accordingly:

• Node.js → index.js or index.mjs
• Python → index.py
• Ruby → index.rb
• Java → packaged in a jar (not applicable here)

Now confirm the deployed artifact’s filename is correct.

---

Step 3: Inspect the zip structure.

Download the live package:

aws lambda get-function \
  --function-name my-function \
  --query 'Code.Location' \
  --output text > url.txt

curl -L "$(cat url.txt)" -o current.zip
unzip -l current.zip

Correct structure:

index.js
package.json
node_modules/

Incorrect nested structure:

project/
project/index.js
project/node_modules/

If you see nesting, Lambda cannot see your index module.

---

Step 4: Verify handler matches file name exactly.

Handler in Lambda config:

index.handler

Must correspond to:

• A file named index.js
• A function named handler inside it
• Exact casing — Lambda is case-sensitive

If the handler and module disagree, fix the configuration.

---

Step 5: Rebuild a clean, flat zip.

From inside your project directory:

zip -r ../deploy.zip .

This ensures code sits at the root, not inside a folder.

Confirm again:

unzip -l ../deploy.zip

Should show index.js at the top level.

---

Step 6: Deploy and retest.

aws lambda update-function-code \
  --function-name my-function \
  --zip-file fileb://deploy.zip

Then invoke:

aws lambda invoke \
  --function-name my-function \
  --payload '{}' \
  out.json

If no error appears, module resolution is fixed.

---

Pro Tips

1. Keep filenames predictable

Use simple, lowercase module names to avoid casing issues.

2. Avoid nested folders

Zip the contents, not the directory.

3. Check runtime before coding

Runtime determines module type — don’t mix Node.js formats.

---

Conclusion

“Cannot find module './index'” means Lambda could not locate the module file that defines your handler. Once the runtime, filename, handler string, and zip structure are aligned, Lambda starts cleanly and executes your code as expected.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.