Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A Lambda container image crashes locally with KeyError: AWS_LAMBDA_RUNTIME_API

ErrorKeyError: 'AWS_LAMBDA_RUNTIME_API'

Short answer

The Lambda runtime interface client reads AWS_LAMBDA_RUNTIME_API at start-up. Lambda sets it; a plain docker run does not. Run the image through the runtime interface emulator, which the AWS base images already include, or mount the emulator and use it as the entrypoint for any other base image.

  • Applies to Python 3.12 Lambda image, Docker 25, awslambdaric
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which base image you build from and whether the Dockerfile sets its own ENTRYPOINT. Those two facts decide which cause applies.

    grep -n -E "^(FROM|ENTRYPOINT|CMD)" Dockerfile
  2. 2Match what you see, then jump to its fix

    1. 1FROM is python:3.x or another image from outside public.ecr.aws/lambda, and ENTRYPOINT is python -m awslambdaricA non-AWS base image runs the runtime client without the emulatorFix
    2. 2FROM public.ecr.aws/lambda/python:3.12 and the Dockerfile also sets ENTRYPOINTAn AWS base image, but ENTRYPOINT was overriddenFix

What does the error look like?

  • KeyError: 'AWS_LAMBDA_RUNTIME_API'

Cause 1 of 2

A non-AWS base image runs the runtime client without the emulator

1Check

AWS base images ship the runtime interface client and the emulator. For any other base image you add the client yourself, and for local tests you must add the emulator too. Without it nothing provides the Lambda runtime API.

docker run --rm --entrypoint env my-image:test | grep AWS_LAMBDA

2Fix

Download the emulator on your machine, mount it into the container and make it the entrypoint, followed by the same command your Dockerfile uses.

mkdir -p ~/.aws-lambda-rie && \
  curl -Lo ~/.aws-lambda-rie/aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie && \
  chmod +x ~/.aws-lambda-rie/aws-lambda-rie

docker run --platform linux/amd64 -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \
  --entrypoint /aws-lambda/aws-lambda-rie \
  my-image:test /usr/local/bin/python -m awslambdaric lambda_function.handler

3Verify

Invoke the local endpoint and get the function's response.

curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 2

An AWS base image, but ENTRYPOINT was overridden

1Check

AWS base images come with the emulator preinstalled, and the AWS example for the Python base image sets only CMD to the handler name. A custom ENTRYPOINT in your Dockerfile replaces the image's own start command, so the emulator no longer starts.

docker inspect --format '{{json .Config.Entrypoint}}' my-image:test

2Fix

Delete your ENTRYPOINT line and pass the handler as CMD.

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

3Verify

Run the image on port 9000 and post an event.

docker run --platform linux/amd64 -p 9000:8080 my-image:test
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Test every Lambda image with the emulator before you push it to the registry.
  • Build from an AWS base image unless you need something it cannot give you.
  • Build for the platform of the function: pass --platform linux/amd64 or linux/arm64 on build and run.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.