[vicheey]

Which issue(s) does this change fix?

Follow-up to #9366 (CI-side fix).

Why is this change necessary?

With Finch, SAM CLI can pull images without registry credentials even after finch login, hits registry rate limits (429), and shows a misleading 404 … no such image.

• macOS: finch login writes ~/.finch/config.json (or $DOCKER_CONFIG), but docker-py only reads the Docker config.
• Linux: a first sudo/setuid finch login can leave ~/.docker/config.json root-owned; docker-py silently treats an unreadable config as missing.
• All platforms: finch-daemon reports auth and rate-limit failures as 404, and SAM CLI drops errors from the pull stream and the underlying cause from its error message.

How does it address the issue?

• Credentials loaded once per client: ContainerClient loads registry credentials at creation, so pulls, builds and pushes authenticate the same way. Finch on macOS loads $DOCKER_CONFIG/config.json or ~/.finch/config.json via docker-py's public reload_config; Docker and Finch on Linux keep docker-py's default behavior.
• Single pull path: new ContainerClient.pull_image() / pull_image_and_wait() raise on rejected pulls and on errors reported in the stream. Used by ContainerManager and the durable functions emulator.
• Real errors surfaced: "failed to pull" messages include the underlying cause; the emulator pull failure is a UserException with wrapped_from for metrics.
• Finch guidance: warns once when the Docker config exists but can't be read, and appends finch login guidance to Finch pull failures that look like auth, not-found or rate-limit errors.
• Credential-store errors don't fail the command: a missing credsStore/credHelpers helper logs a warning and the pull retries anonymously.
• Naming: runtime-neutral names move from Docker* to Container*: ContainerImagePullFailedException (moved to samcli/local/docker/exceptions.py), ContainerCreationFailedException, private attributes, and user-facing messages ("container image").

What side effects does this change have?

• No change for Docker users beyond clearer pull error messages.
• DockerImagePullFailedException and DockerContainerCreationFailedException are renamed; no external users were found.
• New one-time warnings may appear for Finch users with an unreadable Docker config or a missing credential helper.
• No new dependencies; only public docker-py APIs are used.

Mandatory Checklist

PRs will only be reviewed after checklist is complete

• Review the generative AI contribution guidelines
• Add input/output type hints to new functions/methods
• Write design document if needed (Do I need to write a design document?)
• Write/update unit tests
• Write/update integration tests
• Write/update functional tests if needed
• make pr passes
• make update-reproducible-reqs if dependencies were changed
• Write documentation

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[aws-sam-tooling-bot]

🧪 Hands-on test: No problems observed in 8 scenarios

Commit 630a94f · build LambdaToolingHandsOn-Docker:f09f6584-4dae-4a81-a302-d9b79fac11d2. The plan's scenarios ran on an isolated build host; a problem is reported only if it reproduced at least twice. Passing scenarios show only that these checks behaved as expected, not that the change is correct.

Scenarios

Scenario	Planned check	Result	Runner's note
S1	The unit tests for the changed modules pass: container client, factory, platform config, manager, durable emulator, inv…	✅ pass	Head: 597 passed for the 8 planned test files. The other changed test files (lambda_image, app_builder, ecr_uploader, sync flow, package_context, local_lambda_http_service, container) pass serially o…
S2	sam build --use-container with a build image that doesn't exist: the error now includes the registry's cause instead of…	✅ pass	Run with 'python -m samcli' from each venv: PATH 'sam' resolves to a system /usr/local/bin/sam 1.169.0 binary, so the first attempts (logs 13/14) tested neither tree and are discarded. Head (exit 1):…
S3	A Docker config whose credsStore names a helper that isn't installed: the PR warns once and pulls a public image anonym…	✅ pass	DOCKER_CONFIG with credsStore 'samhandson-missing', alpine image removed first. Base: 'RESULT=fail DockerException Credentials store error: StoreError(docker-credential-samhandson-missing not install…
S4	Finch registry-config loading (macOS path simulated by patching get_finch_registry_config_path): a valid config is used…	✅ pass	Head, exit 0: 'LINUX_PATH None', 'CASE ok True', 'CASE bad False' twice with only one 'Could not read registry config .../bad.json' warning, 'CASE helper False' with a warning naming docker-credentia…
S5	pull_image raises on errors in the stream. Finch adds 'finch login' guidance only for auth, not-found and rate-limit er…	✅ pass	Head, exit 0. Finch: 'toomanyrequests' and 'not found' raise ContainerImagePullFailedException with the original error plus 'run `finch login ` ... ~/.docker/config.json'. 'no space left on…
S6	The unreadable-Docker-config warning comes only from Finch, only once per process, and not when the Finch config is in …	✅ pass	Head, uid 1002. With _is_docker_config_readable patched to False: the Docker client logs nothing. The Finch client called twice, plus a second Finch instance, gives exactly one warning ('The registry…
S7	Regression check: a normal sam local invoke of a ZIP function on Docker still works after the client-attribute renames,…	✅ pass	Head 'python -m samcli local invoke Fn -e -' on Docker for a python3.12 ZIP function: exit=0, stdout '"hello"'. stderr shows the rapid image build and a normal START/END/REPORT, with no traceback, 'f…
S8	When the durable functions emulator image can't be pulled and isn't local, the error is now a UserException with wrappe…	✅ pass	Emulator tag samcli-handson-no-such-tag. Head: 'TYPE UserException ContainerImagePullFailedException', MSG 'Failed to pull emulator image public.ecr.aws/durable-functions/aws-durable-execution-emulat…

_{🤖 Automated hands-on test — not a review approval · model claude-opus-5.5 · Kiro kiro-cli 2.33.1 · build LambdaToolingHandsOn-Docker:f09f6584-4dae-4a81-a302-d9b79fac11d2 · commit 630a94f}

History (1)

Commit	Result	When (UTC)	Build
630a94f	No problems observed	2026-10-23 21:02	LambdaToolingHandsOn-Docker:f09f6584-4dae-4a81-a302-d9b79fac11d2