Lambda Python: fix a handler import error

Separate module loading from function execution

Read the exact import error and the configured handler. A missing handler module prevents the application function from being called. A dependency imported by that module can also be missing, so identify the name in the error instead of assuming app.py itself is absent.

In our local runtime test, app.handler was configured but app.py existed only inside src. The runtime reported Runtime.ImportModuleError. An execution-role policy could not repair that filesystem layout.

Inspect the artifact you will actually deploy

List the archive contents rather than only the source tree. For a top-level module named app, the archive should expose app.py at its extraction root, together with the dependencies its imports require. A parent project folder can accidentally add another level.

The command below lists a ZIP without deploying it. Check names and capitalization; a file that appeared to work on a case-insensitive development filesystem can still fail in a Linux runtime.

sh · EXAMPLE

python -m zipfile -l deployment.zip
# For handler app.handler, inspect whether app.py is at the archive root,
# rather than only under project/ or src/.

Build from the intended package directory

For a simple handler, put app.py in a package directory and create the archive from inside that directory. Add required dependencies through the packaging process appropriate to their runtime and architecture. Do not assume every package installed on a laptop is compatible with Lambda.

The example handler returns a small JSON-compatible marker. It deliberately avoids network calls so a failed import can be distinguished from application initialization or downstream access failures.

python · EXAMPLE

# package/app.py
def handler(event, context):
    return {"ok": True, "message": "import-ok"}

Verify the corrected import and invocation

Create a fresh artifact from the intended root, inspect it again, and test it in a matching runtime. For example, a shell with zip available can run the command below. Use the same runtime family and architecture as the intended deployment for dependency checks.

In the official local runtime, our corrected task-root layout returned the expected marker. That establishes the import and invocation path for this minimal handler; it does not validate cloud triggers, execution-role permissions, or native dependency compatibility.

sh · EXAMPLE

# Run from the project directory containing package/:
(cd package && zip -r ../deployment.zip .)
python -m zipfile -l deployment.zip

Check the managed deployment’s selected version

After delivering through the normal deployment workflow, verify the function version or alias actually invoked and its configured handler. A correct local artifact does not help if traffic still targets a previous version or a different function.

If module loading succeeds but initialization then fails, preserve the new error and investigate that stage. Network timeouts, missing environment settings, and handler exceptions are separate failures from importing the module itself.

Know the limits

Tested with the official Lambda Python 3.12 base image and Runtime Interface Emulator. Mounting src/app.py under the task root failed for app.handler; placing app.py at that root succeeded. This validates extracted-directory import behavior, not a managed Lambda ZIP deployment or IAM configuration.

Sources & further reading

A technical publication by CoreTrailKit.

Browse all articles