guides / ecs-exec-format-error troubleshootingupdated 2026-11-15 readelf -h ./app

exec format error on ECS / Fargate - task and image disagree

2026-11-15 By luckyray ECS Fargate docs - kernel 7.0 x86-64 repro

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

  1. aws ecs describe-task-definition → runtimePlatform.cpuArchitecture
  2. docker manifest inspect <image> → which architectures the tag actually offers
  3. Compare. If only one arch exists and it is the wrong one, the task can never start.
  4. 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; }

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.

Related

guides
  1. glibc and libstdc++ versions by distribution — measured, not remembered
  2. version `GLIBCXX_3.4.29' not found — and why copying libstdc++ does not fix it
  3. ldd: not a dynamic executable — what it means (nothing is broken)
  4. bash: cannot execute binary file - what bash actually checked
  5. node: cannot execute binary file - the four ways Node breaks
  6. openshift-install: cannot execute binary file - wrong CPU
  7. exec format error in Docker - measured, with the fix that works
  8. exec format error on Raspberry Pi - 32-bit binary, 64-bit OS
  9. exec format error in WSL - which of the two directions you are in
  10. exec format error on macOS - ELF never runs here