AWS Lambda Error – The runtime failed to start (Container Image Edition)
A practical diagnostic guide for resolving Lambda container image boot failures caused by missing bootstraps, incorrect ENTRYPOINT/CMD, packaging mistakes, or architecture mismatches
Problem
Your Lambda container function deploys successfully, but it immediately fails with:
The runtime failed to start: RequestId: <id> Error: Runtime exited with error: exit status 127
Lambda never hands control to your handler. The container boots, loads your image, tries to start the runtime, and fails before your code executes.
• ENTRYPOINT is wrong
• bootstrap file missing or not executable
• architecture mismatch (x86 vs arm64)
• packaging includes OS libraries incompatible with Lambda
Clarifying the Issue
Lambda behaves differently from standard Docker. You can run a container locally and it “works,” but inside Lambda it fails instantly because Lambda expects a very specific bootstrap contract.
• Lambda requires /var/runtime/bootstrap or a valid ENTRYPOINT implementing the Runtime API
• Using CMD ["app.handler"] works in zip-based Lambda, not containers
• Architecture mismatch causes silent runtime exits
• Containers must respond to /2018-06-01/runtime/invocation/next
Why It Matters
A container that works locally but fails in Lambda is one of the highest-friction deployment blockers. Zero logs. Zero handler execution. No graceful failover.
• Breaks production deploys instantly
• Hard for teams to reproduce locally
• Often requires rebuilding and republishing the image
Key Terms
• Bootstrap — The executable that launches your runtime and talks to the Lambda Runtime API
• ENTRYPOINT — The Docker command Lambda executes when starting your container
• Runtime API — The HTTP interface the container must implement
• Architecture — linux/amd64 vs linux/arm64
Steps at a Glance
- Confirm the runtime boot error
- Verify the image architecture
- Inspect ENTRYPOINT and CMD
- Check for the bootstrap executable
- Ensure bootstrap has executable permissions
- Check the working directory and file paths
- Test the container locally with Lambda Runtime Interface Emulator
- Rebuild, republish, and redeploy
Detailed Steps
Step 1: Confirm the runtime boot error.
Pull recent logs:
aws logs tail /aws/lambda/my-function --since 5m
You should see:
Runtime exited with error: exit status 127
This indicates Lambda could not start your runtime. Next, check architecture.
Step 2: Verify the image architecture.
Run:
docker inspect myimage:latest --format='{{.Architecture}}'
If Lambda is configured for arm64 but the image is amd64, the runtime will fail instantly. Align them before proceeding.
Step 3: Inspect ENTRYPOINT and CMD.
Display the image configuration:
docker inspect myimage:latest --format='{{json .Config}}' | jq .
Lambda expects a real executable at ENTRYPOINT, not a string pointing to your handler.
Example of a broken config:
ENTRYPOINT ["app.handler"]
Correct patterns include:
ENTRYPOINT ["/lambda-entrypoint.sh"]
CMD ["app.handler"]
If ENTRYPOINT is wrong, Lambda will never reach your handler. Now check the bootstrap.
Step 4: Check for the bootstrap executable.
List expected bootstrap:
docker run --rm -it myimage:latest ls -l /var/runtime
Or for custom runtimes:
docker run --rm -it myimage:latest ls -l /var/task
You must see:
bootstrap*
If bootstrap is missing, Lambda can't start your container. Now ensure permissions.
Step 5: Ensure bootstrap has executable permissions.
Check:
docker run --rm -it myimage:latest stat /var/task/bootstrap
If it's not executable, fix it:
chmod +x bootstrap
Then rebuild the image:
docker build -t myimage:latest .
Next, confirm file path expectations.
Step 6: Check the working directory and file paths.
Lambda sets the working directory to /var/task. If your application files live somewhere else, your bootstrap or ENTRYPOINT will fail to locate them.
Verify:
docker run --rm -it myimage:latest pwd
docker run --rm -it myimage:latest ls -l /var/task
If the app is buried in /home/app/project/dist, Lambda won’t find it. Fix your Dockerfile. Now test the container locally with the emulator.
Step 7: Test locally with Lambda Runtime Interface Emulator.
Run:
docker run -p 9000:8080 myimage:latest
Invoke:
curl "http://localhost:9000/2015-03-31/functions/function/invocations" \
-d '{}'
If it fails locally under LAMBDA_RIE, it will fail in AWS. Once fixed, rebuild the image.
Step 8: Rebuild, republish, and redeploy.
docker build -t myimage:latest .
docker tag myimage:latest <account>.dkr.ecr.<region>.amazonaws.com/myimage:latest
docker push <account>.dkr.ecr.<region>.amazonaws.com/myimage:latest
Then update Lambda:
aws lambda update-function-code \
--function-name my-function \
--image-uri <uri>
Pro Tips
Use official Lambda base images
They automatically include required runtime API functionality.
Avoid copying the entire filesystem
Keep the image lean; avoid unexpected binary dependencies.
Use arm64 only if your native libs support it
Otherwise runtime will crash instantly.
Conclusion
Container-based runtime failures happen when Lambda cannot execute your image’s bootstrap or ENTRYPOINT. By validating architecture, ensuring a proper bootstrap, confirming permissions, and testing with the Runtime Interface Emulator, you can restore clean startup behavior and eliminate hidden container boot errors.
Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.
Comments
Post a Comment