exec format error on ECS / Fargate - task and image disagree
On ECS you do not get a shell message; you get a task that stops seconds after starting,
with exec format error buried in the container's stopped reason. The cause is always the
same: the image architecture and the runtime platform architecture are different.
Two settings must agree
Fargate takes the architecture from the task definition, not from the image:
| Where | Field | Default |
|---|---|---|
| Task definition | runtimePlatform.cpuArchitecture |
X86_64 |
| The image itself | the manifest the registry serves | whatever was built |
If you built an arm64 image and left cpuArchitecture alone, Fargate schedules an x86-64
microVM, pulls your arm64 image, and the entrypoint fails to exec. The reverse (an amd64
image on ARM64 tasks) fails the same way.
The parameter is documented in
Amazon ECS task definition parameters for Fargate,
where cpuArchitecture defaults to X86_64 when not set.
Why the error is easy to miss
Task stopped: EssentialContainerExited
Stopped reason: exec format error
Nothing in that message mentions architecture, and the task definition looks fine if you only
read the image tag — myapp:1.2 says nothing about CPU. Registries serve whatever manifest
the tag points at.
Confirm which architecture you actually have
# what the image offers
docker manifest inspect myorg/myapp:1.2 | grep -E '"architecture"'
"architecture": "arm64",
# what the task asks for
aws ecs describe-task-definition --task-definition myapp:12 \
--query 'taskDefinition.runtimePlatform'
{
"cpuArchitecture": "X86_64",
"operatingSystemFamily": "LINUX"
}
One is arm64, the other X86_64. That is the whole bug.
The fix, depending on what you want
Keep the image: switch the task definition
aws ecs register-task-definition \
--cli-input-json file://taskdef.json # with runtimePlatform.cpuArchitecture = ARM64
Requires Fargate platform version 1.4.0+ for ARM64.
Keep x86 tasks: build the image for amd64
docker buildx build --platform linux/amd64 -t myorg/myapp:1.3 --push .
This is the common case when a developer on an Apple Silicon laptop builds locally and pushes
without --platform: the image is arm64, and every x86 Fargate task fails at startup.
Best: publish both
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myorg/myapp:1.3 --push .
The registry then serves a manifest list (a multi-arch image). Fargate picks the variant that
matches cpuArchitecture automatically, and the same tag works for both.
Check that it worked:
docker manifest inspect myorg/myapp:1.3 | grep architecture
"architecture": "amd64",
"architecture": "arm64",
The same failure, reproduced outside ECS
The kernel behaviour is not ECS-specific. Measured on an x86-64 host with Docker 29.1.3:
$ docker run --rm --platform linux/arm64 alpine:3.20 uname -m
exec /bin/uname: exec format error
With a foreign-architecture handler registered, the same command returns aarch64:
$ docker run --privileged --rm tonistiigi/binfmt --install arm64
$ docker run --rm --platform linux/arm64 alpine:3.20 uname -m
aarch64
Fargate does not give you that option — there is no emulation layer in the task VM. The architecture has to match.
Checklist for a failing ECS task
aws ecs describe-task-definition→runtimePlatform.cpuArchitecturedocker manifest inspect <image>→ which architectures the tag actually offers- Compare. If only one arch exists and it is the wrong one, the task can never start.
- If you build in CI, assert the platform in the build step — never inherit the runner's.
# CI guard: fail the build instead of the deployment
docker buildx build --platform linux/amd64 -t "$IMAGE" --push .
docker manifest inspect "$IMAGE" | grep -q '"architecture": "amd64"' \
|| { echo "image is not amd64"; exit 1; }
Related errors that look similar
| Message | Cause |
|---|---|
exec format error |
Architecture mismatch (this article) |
exec /app/start: no such file or directory |
The image's loader is missing — glibc binary in an Alpine base |
CannotPullContainerError |
Registry/permissions, not architecture |
The middle one is the trap: the file is present, its interpreter is not. Fixing it means
rebuilding against the target libc, not changing cpuArchitecture.
The cpuArchitecture default and behaviour are from the AWS ECS Fargate task definition
documentation. The kernel-level failure was reproduced locally on Docker 29.1.3 / kernel 7.0
x86-64 with a linux/arm64 image, before and after registering qemu-aarch64.