Solve: Fixing the ECS-CDK First Deploy Error—The Real-World Solution

Solve: Fixing the ECS-CDK First Deploy Error—The Real-World Solution

When you're deploying an ECS service with AWS CDK for the first time, and that service depends on a Docker image in ECR, you're likely to hit a frustrating wall. CloudFormation fails, ECS can’t launch, and the deploy process collapses—not because your code is broken, but because of the order in which everything is expected to exist.

This problem shows up most often in projects where your CI/CD pipeline is responsible for building and pushing the image. But the pipeline won’t run until the infrastructure is up... and the infrastructure won’t come up because ECS can’t find the image. You’re stuck in a circular dependency.

Let’s break it down and solve it for real.

The Fix at a Glance

1. Understand the error — ECS tries to launch with a Docker image that doesn’t exist yet.
2. Deploy with a placeholder — Use a public container image so your CDK deploy succeeds.
3. Let the pipeline run — Once the stack is up, your CI/CD system builds and pushes your real image to ECR.
4. Update the service — Redeploy with your actual image to complete the cycle cleanly.

This is a practical, reliable pattern—not a workaround. It’s how you bootstrap ECS services when infrastructure and application containers are being created together for the first time.

Phase 1: Why the First Deploy Fails

When your ECS service is defined in CDK using a Docker image that doesn't yet exist in ECR, the CDK stack compiles and deploys—but fails at the ECS level. The container agent attempts to pull the image during service launch, hits a 404, and the whole deployment rolls back.

This is especially common in unified stacks, where the ECS service and the pipeline that builds the image are deployed together. CDK can't defer ECS startup until the pipeline finishes—so it tries to launch with an image that hasn’t been pushed yet.

Phase 2: Deploy with a Placeholder Image

To break the cycle, use a known-good public container image for the initial deployment. This lets ECS spin up successfully even though your real image isn’t ready.

For example, this CDK snippet sets the service to use the Amazon-provided sample image:

typescript

image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample')

We’ve published a GitHub Gist with a complete CDK stack that shows how to define a working Fargate service using this placeholder approach. It creates a VPC, ECS cluster, task definition, and service—all wired up and ready for real-world use.

Once deployed, this stack gives your pipeline a live, working ECS target to connect to.

Phase 3: Let the Pipeline Do Its Job

Now that the ECS service exists and the infrastructure is live, your pipeline can do what it was designed to do: build and push your real container image to ECR. Whether you’re using GitHub Actions, AWS CodeBuild, or something else, this happens independently of CDK.

The important part is that you're no longer blocked. Your infrastructure is up, your pipeline can now publish the real image, and ECS is no longer referencing something that doesn’t exist.

Phase 4: Update the Service with the Real Image

With your image successfully built and stored in ECR, you now return to your CDK code and update the task definition to reference your actual image: 

typescript

image: ecs.ContainerImage.fromEcrRepository(myRepo, 'latest')

Then run: 

bash

cdk diff 
cdk deploy

This redeploys your ECS service, updating the container configuration while leaving the rest of your stack intact. You’ve now completed the bootstrapping cycle with a real, production-grade image and a clean deploy history.

If you prefer, you can also make this switch manually via update-service in the AWS CLI or console—but sticking with CDK keeps your infrastructure as code, where it belongs.

Wrap-Up: A Pattern You’ll Use Again and Again

This four-step fix isn’t just for ECS. It reflects a common pattern across cloud deployments: sometimes you need to deploy a placeholder just to get the system online, and then bring in the real artifacts once they’re ready. That principle applies to ECR, S3, Lambda, and more.

So next time you hit the "image not found" wall, you’ll know what to do: deploy the shell first, let the pipeline fill it in, and then make one clean update to go live.

* * * 

Written by Aaron Rose, software engineer and technology writer at Tech-Reader.blog.