The build could not pull a container image

WHAT IT MEANS

What this error means

Error response from daemon: pull access denied for myco/base,
repository does not exist or may require 'docker login'

Start with what the prefix tells you: Error response from daemon means the daemon replied, so the daemon is running. This is not a "Docker is not available" problem, and checking docker.sock or restarting Docker will not change the outcome.

The message hedges between two causes because the registry deliberately will not say which: answering "that image is private" differently from "that image does not exist" would let anyone enumerate private repository names. So one error covers both:

• Not authenticated. The job never logged in to the registry, or logged in after the build step, or the ECR authorization token expired mid-job (they last 12 hours).
• The image or tag genuinely is not there. A tag that was never pushed, a typo, or a digest from a registry in another account or Region.
• The tag exists for a different architecture. An arm64-only image requested for an x86_64 build reports as a missing manifest, which reads like a typo but is not one.

FIX

How to fix it

1. Reproduce it outside SAM on the failing runner, which separates a registry problem from a SAM one in a single command:

   docker pull <image>:<tag>

2. For a private registry, log in in the same job — and check the login step runs before the build, which is the usual ordering mistake:

   aws ecr get-login-password --region <region> \
     | docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com

3. Confirm the tag exists before assuming permissions:

   aws ecr describe-images --repository-name <repo> --image-ids imageTag=<tag>

4. Check the architecture matches the function's Architectures. An image built only for linux/arm64 cannot satisfy an x86_64 build.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor separates a registry refusal (high confidence) from an unreachable Docker daemon, which the two failures used to share. Runs locally; no AWS access, no log upload.

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED

Related errors

• no basic auth credentials — the runner never authenticated to the registry at all.
• SAM build requires Docker — when the daemon really is unreachable.
• No space left on device — the other failure that surfaces from inside a container build.