SAM local "Unable to find image public.ecr.aws/lambda" in CI

sam local pulls a runtime emulation image from public.ecr.aws/lambda to run your function. If the pull fails (offline, registry throttling, or a wrong tag), SAM cannot start the container and the invoke aborts.

What this error means

sam local invoke prints "Unable to find image 'public.ecr.aws/lambda/nodejs:20-rapid-x86_64' locally" followed by a pull error, or hangs and fails fetching the base image.

Unable to find image 'public.ecr.aws/lambda/nodejs:20-rapid-x86_64' locally
Error: Could not find amazon/aws-sam-cli-emulation-image ... : pull access denied

Common causes

No network access to public.ecr.aws

An offline or egress-restricted runner cannot reach the public ECR registry to pull the emulation image.

Registry rate limiting or a stale tag

Public ECR throttled the anonymous pull, or the runtime tag SAM requests no longer exists for that architecture.

How to fix it

Pre-pull the emulation image

1. Pull the base image explicitly in a setup step so the invoke reuses it.
2. Cache the Docker layers between runs where possible.
3. Run sam local invoke after the image is present.

docker pull public.ecr.aws/lambda/nodejs:20
sam local invoke MyFunction -e event.json

Use a mirror or authenticate to ECR

Point Docker at an internal mirror of the public ECR image, or log in to raise the anonymous pull limit.

aws ecr-public get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin public.ecr.aws

How to prevent it

• Pre-pull or cache the Lambda emulation image in CI.
• Mirror public ECR images internally for egress-restricted runners.
• Pin runtime versions that publish the expected tags.

Related guides