Bug: sam local invoke - DockerException - missing credential helper

[miketheman]

Description:

On a fresh project, using the default hello_world template from sam init, the a failure is shown when attempting to invoke locally.

Steps to reproduce:

$ sam init \
  --name=demo-failure \
  --architecture=x86_64 \
  --runtime=python3.13 \
  --dependency-manager=pip \
  --package-type=Zip \
  --app-template=hello-world \
  --no-tracing \
  --no-application-insights \
  --no-structured-logging \
  --no-beta-features
$ cd demo-failure
$ sam build
$ sam local invoke --debug

Observed result:

$ sam local invoke --debug
2024-12-08 16:48:34,845 | Config file location: /tmp/workspace/samconfig.toml
2024-12-08 16:48:34,847 | Loading configuration values from [default.['local', 'invoke'].parameters] (env.command_name.section) in config file at
'/tmp/workspace/samconfig.toml'...
2024-12-08 16:48:34,848 | Configuration values successfully loaded.
2024-12-08 16:48:34,849 | Configuration values are: {'stack_name': 'demo-python-types-packaging'}
2024-12-08 16:48:34,852 | Using SAM Template at /tmp/workspace/.aws-sam/build/template.yaml
2024-12-08 16:48:34,884 | Using config file: samconfig.toml, config environment: default
2024-12-08 16:48:34,885 | Expand command line arguments to:
2024-12-08 16:48:34,885 | --template_file=/tmp/workspace/.aws-sam/build/template.yaml --no_event --layer_cache_basedir=/Users/miketheman/.aws-sam/layers-pkg
--container_host=localhost --container_host_interface=127.0.0.1
2024-12-08 16:48:34,886 | local invoke command is called
2024-12-08 16:48:35,070 | No Parameters detected in the template
2024-12-08 16:48:35,095 | Sam customer defined id is more priority than other IDs. Customer defined id for resource HelloWorldFunction is HelloWorldFunction
2024-12-08 16:48:35,096 | There is no customer defined id or cdk path defined for resource ServerlessRestApi, so we will use the resource logical id as the resource id
2024-12-08 16:48:35,097 | 0 stacks found in the template
2024-12-08 16:48:35,098 | No Parameters detected in the template
2024-12-08 16:48:35,118 | Sam customer defined id is more priority than other IDs. Customer defined id for resource HelloWorldFunction is HelloWorldFunction
2024-12-08 16:48:35,119 | There is no customer defined id or cdk path defined for resource ServerlessRestApi, so we will use the resource logical id as the resource id
2024-12-08 16:48:35,120 | 2 resources found in the stack
2024-12-08 16:48:35,120 | Found Serverless function with name='HelloWorldFunction' and CodeUri='HelloWorldFunction'
2024-12-08 16:48:35,121 | --base-dir is not presented, adjusting uri HelloWorldFunction relative to /tmp/workspace/.aws-sam/build/template.yaml
2024-12-08 16:48:35,131 | Found one Lambda function with name 'HelloWorldFunction'
2024-12-08 16:48:35,131 | Invoking app.lambda_handler (python3.13)
2024-12-08 16:48:35,132 | No environment variables found for function 'HelloWorldFunction'
2024-12-08 16:48:35,133 | Loading AWS credentials from session with profile 'None'
2024-12-08 16:48:35,144 | Resolving code path. Cwd=/tmp/workspace/.aws-sam/build,
CodeUri=/tmp/workspace/.aws-sam/build/HelloWorldFunction
2024-12-08 16:48:35,145 | Resolved absolute path to code is /tmp/workspace/.aws-sam/build/HelloWorldFunction
2024-12-08 16:48:35,146 | Resolving code path. Cwd=/tmp/workspace/.aws-sam/build,
CodeUri=/tmp/workspace/.aws-sam/build/HelloWorldFunction
2024-12-08 16:48:35,147 | Resolved real code path to /tmp/workspace/.aws-sam/build/HelloWorldFunction
2024-12-08 16:48:35,147 | Code /tmp/workspace/.aws-sam/build/HelloWorldFunction is not a zip/jar file
2024-12-08 16:48:35,151 | Local image was not found.
2024-12-08 16:48:35,152 | Removing rapid images for repo public.ecr.aws/sam/emulation-python3.13
Building image.../usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/docker/credentials/store.py:21: UserWarning: docker-credential-ecr-login not installed or not available in PATH
  warnings.warn(
2024-12-08 16:48:35,313 | Cleaning all decompressed code dirs
2024-12-08 16:48:35,314 | Telemetry endpoint configured to be https://aws-serverless-tools-telemetry.us-west-2.amazonaws.com/metrics
2024-12-08 16:48:35,316 | Telemetry endpoint configured to be https://aws-serverless-tools-telemetry.us-west-2.amazonaws.com/metrics
2024-12-08 16:48:35,317 | Unable to find Click Context for getting session_id.

Error: Credentials store error: StoreError('docker-credential-ecr-login not installed or not available in PATH')
Traceback:
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/cli/cli_config_file.py", line 347, in wrapper
    return func(*args, **kwargs)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/click/decorators.py", line 92, in new_func
    return ctx.invoke(f, obj, *args, **kwargs)
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/lib/telemetry/metric.py", line 185, in wrapped
    raise exception  # pylint: disable=raising-bad-type
    ^^^^^^^^^^^^^^^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/lib/telemetry/metric.py", line 150, in wrapped
    return_value = func(*args, **kwargs)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/lib/utils/version_checker.py", line 43, in wrapped
    actual_result = func(*args, **kwargs)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/cli/main.py", line 95, in wrapper
    return func(*args, **kwargs)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/commands/local/invoke/cli.py", line 108, in cli
    do_cli(
    ~~~~~~^
        ctx,
        ^^^^
    ...<21 lines>...
        hook_name,
        ^^^^^^^^^^
    )  # pragma: no cover
    ^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/commands/local/invoke/cli.py", line 209, in do_cli
    context.local_lambda_runner.invoke(
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        context.function_identifier, event=event_data, stdout=context.stdout, stderr=context.stderr
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/commands/local/lib/local_lambda.py", line 166, in invoke
    self.local_runtime.invoke(
    ~~~~~~~~~~~~~~~~~~~~~~~~~^
        config,
        ^^^^^^^
    ...<6 lines>...
        extra_hosts=self.extra_hosts,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/lib/telemetry/metric.py", line 325, in wrapped_func
    return_value = func(*args, **kwargs)
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/local/lambdafn/runtime.py", line 224, in invoke
    container = self.create(
        function_config, debug_context, container_host, container_host_interface, extra_hosts
    )
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/local/lambdafn/runtime.py", line 96, in create
    container = LambdaContainer(
        function_config.runtime,
    ...<14 lines>...
        function_full_path=function_config.full_path,
    )
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/local/docker/lambda_container.py", line 103, in __init__
    image = LambdaContainer._get_image(
        lambda_image, runtime, packagetype, imageuri, layers, architecture, function_full_path
    )
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/local/docker/lambda_container.py", line 257, in _get_image
    return lambda_image.build(runtime, packagetype, image, layers, architecture, function_name=function_name)
           ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/local/docker/lambda_image.py", line 250, in build
    self._build_image(
    ~~~~~~~~~~~~~~~~~^
        image if image else base_image, rapid_image, downloaded_layers, architecture, stream=stream_writer
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/samcli/local/docker/lambda_image.py", line 349, in _build_image
    resp_stream = self.docker_client.api.build(
        fileobj=tarballfile,
    ...<5 lines>...
        platform=get_docker_platform(architecture),
    )
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/docker/api/build.py", line 261, in build
    self._set_auth_headers(headers)
    ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/docker/api/build.py", line 335, in _set_auth_headers
    auth_data = self._auth_configs.get_all_credentials()
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/docker/auth.py", line 298, in get_all_credentials
    auth_data[reg] = self._resolve_authconfig_credstore(
                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        reg, store_name
        ^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/local/Cellar/aws-sam-cli/1.131.0/libexec/lib/python3.13/site-packages/docker/auth.py", line 268, in _resolve_authconfig_credstore
    raise errors.DockerException(
        f'Credentials store error: {repr(e)}'
    ) from e

An unexpected error was encountered while executing "sam local invoke".

Expected result:

Not a failure. Or something upstream that declares a dependency on docker-credential-ecr-login (aka amazon-ecr-credential-helper) so that the failure isn't completely weird.

Additional environment details (Ex: Windows, Mac, Amazon Linux etc)

{
  "version": "1.131.0",
  "system": {
    "python": "3.13.0",
    "os": "macOS-15.1.1-x86_64-i386-64bit-Mach-O"
  },
  "additional_dependencies": {
    "docker_engine": "27.3.1",
    "aws_cdk": "Not available",
    "terraform": "1.5.7"
  },
  "available_beta_feature_env_vars": [
    "SAM_CLI_BETA_FEATURES",
    "SAM_CLI_BETA_BUILD_PERFORMANCE",
    "SAM_CLI_BETA_TERRAFORM_SUPPORT",
    "SAM_CLI_BETA_RUST_CARGO_LAMBDA"
  ]
}

[miketheman]

Also, it's unclear why I'd need a credential helper for a local invoke - so that's weird.

[vicheey]

Hello @miketheman,

Thank you for reporting this issue. The problem is potentially coming from your docker config file.

Solution

1. Please check your docker credential using the following command: vim ~/.docker/config.json
2. In this file, change your credential store from "credsStore": "ecr-login" --> "credsStore": "desktop"
3. Save the file and try sam invoke command again.
   Please refer to https://github.com/awslabs/amazon-ecr-credential-helper for more info about this library.

[mikerosas-mc]

Hello @miketheman,

Thank you for reporting this issue. The problem is potentially coming from your docker config file.

Solution

1. Please check your docker credential using the following command: vim ~/.docker/config.json
2. In this file, change your credential store from "credsStore": "ecr-login" --> "credsStore": "desktop"
3. Save the file and try sam invoke command again.
   Please refer to https://github.com/awslabs/amazon-ecr-credential-helper for more info about this library.

Thanks, this kinda resolved it for me, I removed the credsStore setting completely.

[miketheman]

Thanks all, indeed, it was my local config.

Considering this is a semi-known issue, would it make sense for SAM to emit a more helpful message?

[miketheman]

Also, it's still unclear why Sam wants to use docker for a local invoke for a non-Dockerised application.

[roger-zhangg]

SAM creates a docker and this containerized local environment emulates the cloud-based execution environment of your Lambda function. See more: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started-hello-world.html#serverless-getting-started-hello-world-test

[miketheman]

@roger-zhangg Thanks for the explanation and link! Based on that, this issue is closed.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.