AWS Lambda Error – Cannot find package 'XYZ' imported from …

#aws #lambda #devops #cloud

A diagnostic guide for resolving missing-package failures in AWS Lambda caused by architecture mismatches (Apple Silicon M1–M5), incorrect ZIP structure, OS incompatibility, or bundler exclusions.

While this guide uses the M5 as the latest example, these principles apply to any future architecture where your local development environment diverges from Lambda's execution environment.

Problem

Your Lambda deploys successfully, but fails immediately at invocation with an error like:

Node.js:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'uuid' imported from /var/task/index.js

Python:

ModuleNotFoundError: No module named 'requests'

Lambda has started your runtime, but when your code tried to require or import a specific library, it wasn't there—or worse, it was there, but built for the wrong computer.

Possible causes:

Architecture Mismatch: Installing dependencies on Apple Silicon (M1–M5) and deploying to Linux (x86).
OS Incompatibility: Building on Windows or macOS instead of Amazon Linux.
ZIP Structure: Dependencies trapped inside a sub-folder.
Bundler Exclusions: Webpack/Esbuild marked the library as "external."

Clarifying the Issue

Lambda never installs packages for you. Whatever you upload—ZIP or container—must contain every non-standard library your code needs, pre-compiled for the exact environment Lambda runs on.

If you upload a node_modules folder generated on a Mac (M1 through M5), any package with C++ bindings (like sharp, bcrypt, or protobuf) will fail instantly on Lambda's x86 Linux servers.

⚠️ Warning for AI/ML Developers
The M5 chip is a local AI powerhouse, but AWS Lambda is not.
If you install hardware-optimized libraries locally (like tensorflow-metal or specialized torch builds), they will crash on Lambda. You must build the generic Linux CPU versions of these libraries using the Docker method below.

Steps at a Glance

Check CloudWatch for the exact package name.
Inspect Deployed Artifact (Check for the "Folder Trap").
Identify Target Architecture (x86 vs ARM64).
Reinstall Dependencies (The "Docker" Fix).
Verify Runtime Family (AL2 vs AL2023).
Check Bundler Config (Webpack/Esbuild).
Redeploy and Test.

Detailed Steps

Step 1: Check CloudWatch for the exact package name.

Tail the logs to isolate the culprit:

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

Look for:
Cannot find package 'xyz'

This confirms which specific library is broken.

Step 2: Inspect Deployed Artifact (The "Folder Trap").

Download your function to see what Lambda actually received.

aws lambda get-function --function-name my-function \
  --query 'Code.Location' --output text | xargs curl -o fn.zip

unzip -l fn.zip

Correct Structure:

index.js
node_modules/
  uuid/
package.json

Incorrect:

my-function/       <-- The fatal extra folder
  index.js
  node_modules/

If your dependencies are inside a top-level folder, Lambda cannot see them. Flatten the ZIP.

Step 3: Identify Target Architecture.

Check if your Lambda is running on Intel (Standard) or Graviton (ARM).

aws lambda get-function-configuration --function-name my-fn --query 'Architectures'

["x86_64"] = Intel (Standard)
["arm64"] = Graviton (Cost efficient)

Crucial: You must compile your dependencies for this specific architecture.

Step 4: Reinstall Dependencies (The "Docker" Fix).

This is the most common fix for modern developers.
If you are on an Apple Silicon device (M1 through M5), your local npm or pip installs ARM64 binaries (often with Mac-specific optimizations). If you deploy those to an x86 Lambda, they crash.

Use Docker to build dependencies that match your Lambda perfectly.

For Node.js (x86_64 Lambda):

docker run --rm --platform linux/amd64 -v "$PWD":/app -w /app amazonlinux:2023 \
  bash -c "npm ci && zip -r function.zip ."

For Node.js (ARM64/Graviton Lambda):

docker run --rm --platform linux/arm64 -v "$PWD":/app -w /app amazonlinux:2023 \
  bash -c "npm ci && zip -r function.zip ."

For Python (x86_64 Lambda):
Even though Python is often cross-platform, libraries like numpy or pandas have C-extensions. We force the platform to be safe.

docker run --rm --platform linux/amd64 -v "$PWD":/app -w /app amazonlinux:2023 \
  bash -c "pip install -r requirements.txt -t . && zip -r function.zip ."

For Python (ARM64/Graviton Lambda):

docker run --rm --platform linux/arm64 -v "$PWD":/app -w /app amazonlinux:2023 \
  bash -c "pip install -r requirements.txt -t . && zip -r function.zip ."

Note: The first run may take a moment to pull the Docker image; subsequent builds will be instant due to caching.

Step 5: Verify Runtime Family (AL2 vs AL2023).

Amazon recently updated the underlying OS.

Node 18 & Python 3.10: Run on Amazon Linux 2.
Node 20 & Python 3.12: Run on Amazon Linux 2023.

Check your function's runtime:

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

If you use a build server running Amazon Linux 2, but deploy to Node 20 (AL2023), system libraries (like glibc) may be missing. Ensure your Docker image tag (amazonlinux:2 vs amazonlinux:2023) matches your Lambda Runtime.

Step 6: Check Bundler Config (Webpack/Esbuild).

If you use a bundler, you might be accidentally excluding the package.

Check your esbuild or webpack.config.js for externals.

external: ['aws-sdk', 'sharp'] // Is your missing package listed here?

If a package is listed as "external," the bundler assumes you are providing it via a Lambda Layer. If you aren't using a Layer, remove it from this list so it gets bundled into the file.

Step 7: Redeploy and Test.

Upload the clean artifact:

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

Invoke it:

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

Pro Tips

Don't zip the folder: Always cd into the folder and run zip -r ../fn.zip ..
Python Hygiene: For ZIP deployments, keep libraries in the root. If using Lambda Layers, the structure must be exact: python/lib/python3.12/site-packages/
Consider Container Images: If you constantly fight native dependency issues, consider switching Lambda deployment modes from "Zip" to "Container Image." This allows you to define the OS and dependencies in a Dockerfile and guarantees the build environment matches the runtime.

Conclusion

"Cannot find package" is rarely a code error—it is a build artifact error.

By ensuring your ZIP is flat, your dependencies are built on the correct OS architecture (x86 vs ARM), and your bundler isn't stripping files out, you guarantee that what works on your M5 MacBook Pro also works in the cloud.

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

Search This Blog

Tech-Reader.blog