A Lambda container image crashes locally with KeyError: AWS_LAMBDA_RUNTIME_API
KeyError: '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.
Fix it fast
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)" Dockerfile2Match what you see, then jump to its fix
- 1
FROM 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
FROM public.ecr.aws/lambda/python:3.12 and the Dockerfile also sets ENTRYPOINTAn AWS base image, but ENTRYPOINT was overriddenFix
- 1
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_LAMBDA2Fix
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.handler3Verify
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
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:test2Fix
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
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:
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
docker login to Amazon ECR fails with: Cannot perform an interactive login from a non TTY device
Cannot perform an interactive login from a non TTY device
Docker asked for a password because none reached it, and a pipe or script has no keyboard to answer.
3 causes, each with a fixServers
The Java SDK finds no AWS credentials on an EC2 instance or in a container on it
InstanceProfileCredentialsProvider()
The SDK walks a fixed list of credential sources and the EC2 instance role is the last one.
3 causes, each with a fixServers
cdk deploy fails in a GitLab job with spawnSync docker ENOENT
code: 'ENOENT'
ENOENT means the operating system found no docker program to run.
3 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
pip install cryptography tries to compile and fails in a Docker build
fatal error: 'openssl/aes.h' file not found
cryptography ships prebuilt wheels.
3 causes, each with a fix