`sam local invoke --invoke-image` not using supplied image tag

[geophpherie]

Hello. I am new to AWS SAM and trying to understand how to navigate a situation in which I need to use a slightly different dockerfile for local vs. remote invocation of a lambda (as i need to inject the CA certs my employer requires for local testing, but not remote).

My belief is that --invoke-image should be able to serve this purpose based on the docs suggestion of:

The URI of the container image that you want to use for the local function invocation

However, I am unable to find a situation in which i can point sam to this docker image outside of editing the ImageUri in the built template directly.

What I've tried is to start with the sam init hello world project template for an image that i tagged as main-template for clarity:

Metadata:
  Dockerfile: Dockerfile
  DockerContext: ./hello_world
  DockerTag: main-template

I then took a copy of the provided Dockerfile, edited it slightly to represent my "changes" - for testing this meant replacing CMD ["app.lambda_handler"] with CMD ["app.handler"] (so it would fail if ran but still would build) and tagged it as local-template.

So, looking at the output of sam build the built template has:

      ImageUri: helloworldfunction:main-template
    Metadata:
      DockerContext: /Users/jbeyer/repos/aws-sam-test/sam-app/hello_world
      DockerTag: main-template
      Dockerfile: Dockerfile
      SamResourceId: HelloWorldFunction

Running the command:

sam local invoke HelloWorldFunction --invoke-image local-template

I see the main-template being used:

No current session found, using default AWS::AccountId
Invoking Container created from helloworldfunction:main-template
Building image.................
Using local image: helloworldfunction:rapid-x86_64.

removing all the MetaData from the project file still yields the same results. The only way i can get the local image to be used is edit the ImageUri directly to point to the local-template tag, which will then execute successfully (failed as expected) - but this seemingly defeats the purpose of being able to pass in a different image to be invoked:

      ImageUri: local-template

No current session found, using default AWS::AccountId
Invoking Container created from local-template
Local image was not found.
Removing rapid images for repo local-template
Building image.................
Using local image: local-template:rapid-x86_64.

Can you help me understand what's happening here? How is --invoke-image intended to be used? Is/are there better ways to use a different docker image for local testing while keeping a mostly consistent interface with the cli?

I appreciate any insight you have here, even if it's just me missing something obvious! Thanks!

EDIT: I'm using version 1.137.1 on MacOS 15.4.1

[vicheey]

Hi @geophpherie,

Thanks for the detailed bug report!

To help the us investigate this issue, could you provide:

1. Complete minimal reproduction case - A simple SAM project that demonstrates this issue
2. SAM CLI debug output - Run with --debug flag to see detailed logs:

  sam local invoke HelloWorldFunction --invoke-image local-template --debug

3. Docker images confirmation - Verify both images exist locally:

  docker images | grep -E "(main-template|local-template)"

While this gets fixed, here are some alternatives for your use case:

1. Environment-specific templates
   Create separate template files:

# For local development
sam local invoke -t template-local.yaml


# For deployment  
sam deploy -t template.yaml

2. Parameter overrides
   Use CloudFormation parameters:

Parameters:
  ImageTag:
    Type: String
    Default: main-template

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      ImageUri: !Sub "helloworldfunction:${ImageTag}"

Then override locally:

sam local invoke --parameter-overrides ImageTag=local-template

This appears related to issue #7993 where users also need to use pre-built images that SAM CLI doesn't handle properly with the --invoke-image flag.

This is likely a legitimate bug impacting local testing with custom container images.
Could you provide the additional debug information requested above? This will help the team reproduce and fix the issue.