How do I troubleshoot an “exec format” error that causes my Amazon ECS tasks to fail?

Short Description

This error occurs when tasks ran for a container image are built for a different architecture for your Amazon Elastic Compute Cloud (Amazon EC2) instances. For example, if you built a container image on an ARM-based instance and then try to run the task on a x86 instance.

Note: The task has a stopped reason of "Essential container in task exited" and an exit code 1.

Resolution

To resolve this issue, either change the architecture of your Amazon ECS tasks or rebuild the image for the correct architecture.

Change the architecture of your ECS tasks

The architecture of a task is determined by the cpuArchitecture parameter in the task definition. Valid values are x86_64 and ARM64 with x86_64 as the default value.

To change the architecture used to launch tasks, create a new revision of the task definition with the cpuArchitecture parameter set to the desired value. If the tasks are a part of a service, use the revised architecture to update the service and perform a deployment to launch new tasks.

For Fargate launch types, AWS automatically provisions infrastructure with the correct architecture to run the task. If you use EC2 instances or external instances as your launch type, you must manage capacity for your configuration. For more information, see Capacity management.

Rebuild the image for the correct architecture

Use the same architecture specified in the task definition to rebuild the container image.

Note: Most container image build tools default to the host machine's architecture.

Use Docker or Finch 

Add --platform parameter to the build command to set the target architecture. For example, the Docker build --platform linux/arm64 [...] builds an image for ARM64. The Finch build --plaform linux/amd64 [...] builds an image for the x86/64 architecture.

Example build command:

docker build -t my-image --platform linux/arm64

For more information on the command line client Finch, see Introducing Finch: An Open Source Client for Container Development.

For more information on how to build Docker images, see Building multi-platform images on the Docker website.

AWS CDK

Use the AWS Cloud Development Kit (AWS CDK) ecs.ContainerImage.fromAsset image to build and upload an image from a Docker file in your source directory. For more information, see Images.

CodeBuild

You can also use AWS CodeBuild with Docker images to configure the architecture. For more information, see Build environment compute modes and types.