How do I resolve "InvalidParameterValueException" errors when I deploy container images to Lambda from Amazon ECR?

Short description

Lambda requires container images to conform to Docker Image Manifest V2 Schema 2 format. Lambda doesn't support Open Container Initiative (OCI) image index manifest lists or provenance attestations. By default, Docker Engine v29 and later versions add provenance attestations.

Resolution

Review the following resolutions based on your specific scenario.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Build single-architecture images

Lambda doesn't support multi-architecture container images or OCI image index manifest lists. The final container image that you deploy to a Lambda function must target only one specific architecture. 

To follow best practices for multiple architectures, take the following actions:

• Build separate images for each architecture that you must support.
• Make sure that you use either the supported architecture x86_64 (amd64) or arm64 (AWS Graviton2).
• Use explicit tagging that includes architecture designation, such as your-image:v1.0.0-amd64 and your-image:v1.0.0-arm64.
• Build for a specific architecture in your function type.
  Example build for x86_64 Lambda functions:

  docker build --platform linux/amd64 --provenance=false -t your-image:amd64 .

  Example build for ARM-based architecture Lambda functions:

  docker build --platform linux/arm64 --provenance=false -t your-image:arm64 .

  Important: When you deploy or update the Lambda function, confirm that the architecture that you select matches the architecture of the Docker image.

Turn off provenance attestations in Docker builds

Docker Buildx version 0.10+ and Docker Engine v29+ turn on provenance attestations by default. These attestations create manifest formats that Lambda doesn't support.

1. To turn off provenance, run the following command:

   docker build --platform linux/amd64 --provenance=false -t your-image:tag .

   Note: Replace your-image with your image name and tag with your image tag.

2. For builds that also generate software bill of materials (SBOM) attestations, run the following command to turn off both provenance and SBOM:

   docker build --platform linux/amd64 --provenance=false --sbom=false -t your-image:tag .

3. After you build with these flags, push the image to ECR and update your Lambda function:

   docker push example-registry/example-repository:example-tag

4. To update the function code, run the following update-function-code AWS CLI command:

   aws lambda update-function-code --function-name example-function \
      --image-uri example-registry/example-repository:example-tag

   Note: Replace example-function with your function name, example-registry with your ECR registry URI, example-repository with your repository name, and example-tag with your image tag.

Configure GitHub Actions workflows

If you use GitHub Actions with the docker build-push-action, then you must turn off attestations. For more information, see build-push-action on the Docker website.

To turn off attestations, add these parameters to your workflow:

- name: Build and push
   uses: docker/build-push-action@v4
   with:
     context: .
     platforms: linux/amd64
     push: true
     tags: your-image:tag
     provenance: false
     sbom: false

Reference specific image digests instead of tags

If you use Docker Buildx to build and push images to ECR with a tag like latest, then Docker creates an image index manifest list. The image index points to platform specific images, and Lambda tries to use the image index instead of the platform specific image. Then, the image index causes deployment to fail.

To resolve this issue, reference the specific SHA256 digest of the actual image instead of the tag.

Complete the following steps:

1. Open the Amazon ECR console.
2. In the navigation pane, under Private registry, choose, choose Repositories.
3. Select your repository.
4. Locate the specific image, and then check the Image manifest type column.
5. Copy the SHA256 digest of the single-platform image manifest Docker Image Manifest V2 Schema 2 or OCI image manifest.
6. To update your Lambda function with the image URI and the SHA256 digest, run the following update-function-code AWS CLI command:

   aws lambda update-function-code --function-name example-function \
      --image-uri example-registry/example-repository@sha256:example-digest

   Note: Replace example-registry with your ECR private registry URI, example-repository with your repository name, and example-digest with the SHA256 digest you copied. Replace example-function with your Lambda function name.

Check image manifest format

To diagnose image structure issues and inspect the image manifest in ECR, run the following batch-get-image AWS CLI command:

aws ecr batch-get-image --repository-name example-repository \
   --image-ids imageTag=latest --region us-east-1 \
   --query 'images[].imageManifest' --output text | jq '.mediaType'

Note: Replace example-repository with your ECR repository name.

Additional troubleshooting

If you continue to experience issues after you use the preceding solutions, then take the following actions:

• Confirm that your ECR repository and Lambda function are in the same AWS Region.

• Make sure that you use Lambda compatible base images. AWS provides base Docker images for Lambda, such as:

  FROM public.ecr.aws/lambda/python:3.12

• To save and inspect the image locally to find unexpected layers or attestations, run the following command:

  docker save your-image:tag -o image.tar
   tar -tf image.tar

• Confirm that there's a valid config.json and manifest.json file in your ECR repository and make sure that there isn't an attestations/ directory.

• If your Lambda function enters a Failed state with a "StateReasonCode: InvalidImage" error message, then the container image format isn't compatible. Rebuild the image with --provenance=false, push the image to Amazon ECR, and then update your Lambda function with the new image.

• Review AWS CloudTrail logs to get the specific error returned during deployment.

Related information

Create a Lambda function using a container image

Selecting and configuring an instruction set architecture for your Lambda function

docker image build on the Docker website

Container image manifest format support in Amazon ECR