Why Terraform Does Not Deploy Your Lambda Container Image

When teams start packaging AWS Lambda functions as container images, a common misunderstanding appears quickly:

“I created the Lambda with Terraform, so why is AWS saying the image does not exist?”

The answer is simple. Terraform can provision the infrastructure that references a container image, but it does not automatically build and publish that image unless you explicitly add that behavior yourself.

The problem

A typical setup includes:

• an ECR repository
• a Lambda function configured to use an image URI
• IAM roles and permissions
• event source mappings such as SQS triggers

Terraform can create all of that.

But if the Lambda is configured to use an image tag such as latest, AWS expects that image to already exist inside the repository. If the repository exists but is empty, Lambda creation fails because the referenced artifact is missing.

That is the key distinction:

• the repository exists
• the image artifact does not

In other words, infrastructure exists, executable content does not.

Why Terraform fails here

Terraform declares desired state for infrastructure resources. In this case, the Lambda resource only says:

“This function should use this image URI.”

It does not mean:

• build a Docker image from my Dockerfile
• upload it to ECR
• version it
• publish it before creating the Lambda

That build-and-push step belongs to the software delivery pipeline, not to the Lambda resource itself.

So the failure is expected when:

1. Terraform creates the ECR repository
2. Terraform tries to create the Lambda
3. the image tag referenced by the Lambda is still missing in ECR

What Terraform manages and what it does not

Terraform is well suited for provisioning:

• the ECR repository
• the Lambda definition
• IAM roles and policies
• queues, triggers, networking, and permissions

Terraform does not natively manage the image build lifecycle for aws_lambda_function.

That means the following step must happen separately:

• docker build
• docker push

Only after that can the Lambda use the image successfully.

The correct deployment flow

For Lambda functions based on container images, the operational sequence is usually:

1. Provision infrastructure
2. Build the container image
3. Push the image to the container registry
4. Create or update the Lambda function so it points to that image

This is why a shell script, Makefile, or CI pipeline is often introduced even in relatively small projects.

“Can this be done with Terraform?”

Yes, but with an important nuance.

You can orchestrate the build and push from Terraform by adding extra mechanisms such as:

• a Docker provider
• null_resource with local-exec
• external build steps triggered around terraform apply

However, this is not the native responsibility of the AWS Lambda Terraform resource, and it often makes the Terraform project harder to maintain.

What mature teams usually do

In production environments, a cleaner separation is common:

CI/CD pipeline

The pipeline is responsible for:

• building the image
• running tests
• pushing the image to ECR
• tagging it with an immutable version such as a commit SHA

Terraform

Terraform is responsible for:

• provisioning the infrastructure
• referencing the published image
• updating the Lambda configuration to use a specific tag or digest

This separation improves reproducibility and avoids mixing infrastructure state management with local Docker behavior.

Why latest creates friction

Using latest is convenient, but it introduces ambiguity.

If a new image is pushed with the same tag, Lambda may still need an explicit update so AWS refreshes the function code. That is why many teams prefer immutable tags, for example:

• commit SHA
• release number
• timestamp-based version

With immutable tags, infrastructure and deployments become easier to reason about.

Practical conclusion

The important lesson is this:

Terraform can provision the infrastructure around a Lambda container image, but it is not the system that produces the image artifact by default.

So if your Lambda creation fails because the image is missing, the real issue is not the ECR repository. The issue is that the referenced image has not been built and pushed yet.

A minimal and pragmatic setup is often enough:

• Terraform for infrastructure
• a shell script or CI job for image build and push

That is usually the simplest approach until the project grows into a more formal deployment pipeline.

Final takeaway

For Lambda container deployments, think in two layers:

• infrastructure provisioning
• artifact delivery

Terraform handles the first very well.

The second still needs a build-and-publish process.

That separation is not a limitation of your project. It is the standard deployment model.