AWS Lambda Function Failed to Start: Fix ImportModuleError, HandlerNotFound, ExitError and InvalidEntrypoint

Simple explanation

When you invoke a Lambda function, AWS has to do several things before it calls your code. It starts a container, loads the runtime (Python interpreter, Node.js engine, etc.), finds your deployment package or container image, imports your code, and then calls your handler function.

Think of it like a car that won’t start versus one that breaks down mid-journey. Both are broken, but the diagnosis is completely different. A startup failure means the engine never turned over. You’re not debugging what happened during the drive — you’re checking whether the car can move at all.

A startup failure means something in that chain broke before the handler was called. Your handler never ran. Lambda reports one of the named error types listed below, or times out during initialization.

A runtime failure is different: Lambda started successfully, your handler ran, and then something failed inside it. An unhandled exception, a timeout waiting for a database, an out-of-memory crash. Those are covered on the Debugging Lambda Failures page.

If you’re not sure which kind you have, check the error type in the response or CloudWatch Logs. Startup failures always report errors before the REPORT line appears, or never produce one at all.

How Lambda startup works

Understanding the startup sequence tells you exactly where to look when it breaks.

1. Container start: Lambda picks an available execution environment or creates a new one (cold start). For container image Lambdas, it pulls the image from Amazon ECR.
2. Runtime load: Lambda starts the language runtime (Python, Node.js, Java, etc.) inside the container.
3. Layer loading: any Lambda Layers attached to the function are mounted at /opt/ in the filesystem.
4. Module import: Lambda imports the file named in your handler config. For Python handler.lambda_handler, it imports handler.py. All top-level code in that file runs at this point.
5. Handler resolution: Lambda finds the specific function named in your handler config (lambda_handler in the Python example) and confirms it exists.
6. Init code execution: any code at module scope runs: global variable assignments, SDK client instantiation, database connection setup.
7. Handler invocation: finally, Lambda calls your handler function with the event and context.

Startup failures happen at steps 2 through 6. If Lambda cannot complete all of these, your handler never gets called.

How to diagnose the error fast

Find the error type in the invocation response or in CloudWatch Logs for your function (/aws/lambda/{function-name}), then match it to the table below.

Match the first column to what you see in the response JSON or logs, then jump to the corresponding section below.

When to use this page

Use this page if your function fails immediately on invocation with one of the error types above, or if you see the function time out during initialization (cold start timeout) rather than during handler execution.

If your function starts successfully but then fails — a timeout, an unhandled exception mid-execution, an out-of-memory error — that is a runtime failure, not a startup failure. See Debugging Lambda Failures for those.

If you’re just getting started with Lambda and haven’t deployed a function yet, Deploying Your First Lambda Function covers the full deployment process and common first-time mistakes.

Missing dependencies or wrong zip structure

The most common Lambda startup failure is a missing library. When you develop locally, libraries live in your virtual environment. The Lambda execution environment only contains what you include in your deployment package, plus a small set of pre-installed AWS SDK libraries.

For Python:

# Wrong: zipping only your source file
zip function.zip handler.py

# Right: install dependencies into the package root first
pip install requests -t ./package
cp handler.py ./package/
cd package && zip -r ../function.zip .

With a requirements.txt:

pip install -r requirements.txt -t ./package
cp handler.py ./package/
cd package && zip -r ../function.zip .

For Node.js:

npm install --production
zip -r function.zip . -x "*.git*"

The node_modules/ directory must be at the root of the zip alongside your handler file.

Lambda Layers let you separate dependencies from your function code. A layer is a zip that Lambda mounts at /opt/ in the execution environment. They’re useful for sharing dependencies across functions, but they don’t remove the requirement that the layer itself is structured correctly.

Wrong handler name or wrong file path

Lambda locates your function using the handler string you configured. The format is filename.function_name for Python and filename.functionName for Node.js, without the file extension.

Python examples:

Node.js examples:

The three most common mistakes:

• The file is named app.py but the handler is set to handler.lambda_handler
• The function is named main but the handler expects lambda_handler
• The handler file is in a subdirectory in the zip (e.g. src/handler.py), which Lambda cannot find

To check and fix your handler using the AWS CLI:

# Check current handler configuration
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'Handler'

# Update the handler string
aws lambda update-function-configuration \
  --function-name my-function \
  --handler app.lambda_handler

Runtime version or architecture mismatch

Runtime version: code that uses syntax or features from a newer Python or Node.js version will fail on an older Lambda runtime. For example, using Python 3.10 match statements on a Python 3.9 Lambda produces a SyntaxError at import time, which Lambda reports as Runtime.ImportModuleError.

# Check what runtime your function is configured to use
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'Runtime'

# Update to a newer runtime
aws lambda update-function-configuration \
  --function-name my-function \
  --runtime python3.12

Architecture mismatch: if you build a deployment package on an arm64 machine (Apple Silicon) and deploy to an x86_64 Lambda, compiled extensions (C libraries, Rust modules, packages with C bindings) will fail with import errors. The pure-Python parts of your code will work, but anything that compiles to native code will not.

Build your deployment package on the same architecture as your Lambda, or use Docker with the correct platform flag:

# Build for x86_64 Lambda even on Apple Silicon
docker run --platform linux/amd64 \
  -v "$PWD":/var/task \
  public.ecr.aws/lambda/python:3.12 \
  pip install -r requirements.txt -t ./package

Then confirm the Lambda architecture setting:

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

Init code crashes before the handler runs

Think of top-level code like the lobby of a building. Everyone passes through it on the way in. If the lobby is on fire, nobody gets upstairs — not the first visitor, not the thousandth. When Lambda imports your file, all top-level code runs once, before any invocation. If it throws, the function never starts.

This includes:

• Global variable assignments
• SDK client creation (boto3.client(...), boto3.resource(...))
• Database connections
• Secret or config fetching
• Any code at module scope

If any of this throws an exception, Lambda reports Runtime.ExitError. The handler was never reached.

What this looks like in code:

import os
import psycopg2

# This line runs when Lambda loads the module:
conn = psycopg2.connect(os.environ["DB_HOST"])  # crashes if DB_HOST is not set

def lambda_handler(event, context):
    ...

The fix: use lazy initialization. Connect only on the first real invocation, then reuse the connection on warm invocations:

import os
import psycopg2

_conn = None  # safe: nothing happens at module load

def get_connection():
    global _conn
    if _conn is None:
        _conn = psycopg2.connect(os.environ["DB_HOST"])
    return _conn

def lambda_handler(event, context):
    conn = get_connection()  # connects on first invocation, reuses afterward
    ...

The same applies to secrets fetching. If your init code calls AWS Secrets Manager at module load time and that call fails (wrong permissions, network unavailable), Lambda reports a startup failure. Fetch secrets inside the handler, or use the lazy initialization pattern above.

Lambda layer conflicts

Lambda Layers are mounted in order at /opt/. Your deployment package at /var/task/ takes precedence over layers. If two layers include different versions of the same library, which version is loaded depends on mount order, and the result can be an incompatible version causing a startup failure.

If your function worked and then started failing after you added or updated a layer, a layer conflict is the likely cause.

Debug steps:

1. Remove layers one at a time to identify which one causes the failure.
2. Check if the same library exists in both your deployment package and a layer. The deployment package always wins.
3. Pin dependency versions to exact versions in both your deployment package and your layers so you know exactly what’s being loaded.

# List current layers attached to a function
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'Layers'

VPC and network-related startup failures

When a Lambda function is inside a VPC, it operates in a private subnet. Private subnets have no direct internet access by default.

If your initialization code tries to call an external API, fetch a configuration file, or connect to an AWS service via its public endpoint, it will fail silently in a private subnet. The failure appears as a timeout during cold start, not as a named startup error.

Check if your Lambda is VPC-attached:

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

If it shows subnets and security groups, the function is inside a VPC.

Fixes:

• Add a NAT gateway in the VPC to give private subnets outbound internet access
• Use VPC endpoints for AWS services (S3, DynamoDB, Secrets Manager, etc.) to avoid the internet path entirely
• Move the network-dependent call inside the handler rather than in top-level init code
• Remove the Lambda from the VPC if it doesn’t actually need to access VPC resources

Cold start latency in VPC functions is not itself a failure. Lambda has handled ENI creation efficiently since 2019. The issue is always about outbound connectivity being blocked.

Container image Lambda failures

Container image Lambdas have their own startup failure patterns on top of the standard ones.

Wrong ENTRYPOINT or CMD (Runtime.InvalidEntrypoint)

Lambda expects the container to run the Lambda Runtime Interface Client (RIC) as its entrypoint. When using the official Lambda base images, this is already set up correctly:

FROM public.ecr.aws/lambda/python:3.12
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY handler.py .
CMD ["handler.lambda_handler"]

If you use a non-Lambda base image (e.g. python:3.12), you must install the RIC and configure the entrypoint yourself:

FROM python:3.12
RUN pip install awslambdaric
COPY handler.py .
ENTRYPOINT ["python", "-m", "awslambdaric"]
CMD ["handler.lambda_handler"]

Image not in ECR in the same region

Lambda pulls container images from Amazon ECR. The ECR repository must be in the same AWS region as your Lambda function. Cross-region image references are not supported.

Missing ECR pull permissions

The Lambda service must be able to pull from the ECR repository. If the ECR repository policy doesn’t allow the Lambda service principal, the function can’t start.

# Verify the image URI your Lambda is using
aws lambda get-function \
  --function-name my-function \
  --query 'Code.ImageUri'

Architecture mismatch for container images

The same arm64 vs x86_64 issue applies to container images. If you build the image on Apple Silicon and push it to ECR without specifying --platform linux/amd64, it won’t run on an x86_64 Lambda.

docker build --platform linux/amd64 -t my-lambda-image .

Startup failure vs runtime failure

Choosing the wrong troubleshooting path wastes time. Here’s how to tell which you’re dealing with:

If you’re unsure whether to use Lambda at all for your use case, Choosing Between EC2, Lambda and Containers explains when each service fits.

Step-by-step troubleshooting checklist

Follow this sequence for any Lambda startup failure:

1. Identify the error type. Check the invocation response JSON for errorType, or search CloudWatch Logs for the function’s log group (/aws/lambda/{function-name}).
2. Check the handler string. Confirm filename.function_name matches exactly: correct file, correct function name, no subdirectory path in the zip.
3. Inspect the deployment package. Unzip locally and verify all dependencies are at the root, not in a subdirectory.
4. Check runtime and architecture. Confirm the Lambda runtime version matches what you developed against, and that the architecture (x86_64 vs arm64) matches any compiled extensions.
5. Audit layer contents. If layers are attached, remove them one at a time to identify conflicts. Check for duplicate library versions.
6. Check VPC and network settings. If the function is VPC-attached, confirm init code doesn’t make outbound network calls that would fail in a private subnet.
7. Test locally. Use SAM CLI to invoke the function with the Lambda execution environment:

   sam local invoke MyFunction --event test-event.json

8. For container images. Confirm ENTRYPOINT/CMD points to the RIC, the image is in ECR in the same region, and the image architecture matches the Lambda configuration.
9. Redeploy and verify. After making changes, deploy and invoke the function. Check Monitoring Lambda metrics to confirm the error rate drops to zero.