GitLab CI "exec format error": ARM and x86 image mismatches
Short answer
"exec /bin/sh: exec format error" means the job's image was built for a different CPU architecture than the runner: usually an arm64 image, built on an Apple Silicon Mac, on an amd64 runner, or an amd64-only image on an Arm64 runner. Check the image's platforms with docker buildx imagetools inspect. Then build it for the runner's architecture, or for both, with docker buildx build --platform linux/amd64,linux/arm64, or run the job on a matching runner: on GitLab.com, the saas-linux-small-amd64 or saas-linux-small-arm64 tag. With the Docker executor, image: docker: platform: picks a platform from a multi-architecture image; running one that doesn't match the host also needs QEMU emulation on the host.
A job fails as soon as its container starts:
exec /bin/sh: exec format error
Sometimes it names another program, such as exec /usr/local/bin/docker-entrypoint.sh: exec format error. Either way, the image was built for a different CPU architecture than the runner. Here’s how to find the mismatch, with GitLab 19.5, and the ways to fix it.
Where the mismatch comes from
| Image | Runner | Typical cause |
|---|---|---|
| arm64 | amd64 (x86_64) | You built and pushed the image on an Apple Silicon Mac |
| amd64 | arm64 (aarch64) | The job runs on an Arm64 runner, such as GitLab.com’s saas-linux-small-arm64 or an AWS Graviton machine |
| amd64-only tool | arm64 | Some GitLab security analyzers, such as SAST and pipeline secret detection, support only amd64 |
Check the image and the runner
List the platforms an image has:
docker buildx imagetools inspect registry.gitlab.com/group/project/app:latest
A multi-architecture image lists several, such as linux/amd64 and linux/arm64; unknown/unknown entries are build attestations. A single-platform image shows no platform list: add --format '{{json .Image}}' to see its architecture. For the runner, a job that does start can print uname -m: x86_64 for amd64, aarch64 for arm64. On GitLab.com, the job’s runner tags say it.
Build for the right architecture
To build an image that runs on both:
docker buildx build --platform linux/amd64,linux/arm64 -t registry.gitlab.com/group/project/app:latest --push .
Building for an architecture your machine doesn’t have needs QEMU emulation: Docker Desktop on a Mac includes it, and on Linux, docker run --privileged --rm tonistiigi/binfmt --install all installs it. Building several platforms at once also needs Docker’s containerd image store; if the build says the docker driver doesn’t support it, as older docker:dind images can, run docker buildx create --use --driver docker-container first. To build only for the runner, use --platform linux/amd64. The same flags work in a CI job that builds with Docker-in-Docker: see Cannot connect to the Docker daemon for that setup.
Or run the job on a matching runner
On GitLab.com, untagged jobs run on saas-linux-small-amd64. To use Arm64, add a tag:
arm-test:
image: node:22
tags:
- saas-linux-small-arm64
script:
- uname -m
- npm test
Medium and larger Arm64 runners need Premium or Ultimate, and bigger runners use more compute minutes: see GitLab compute minutes. On your own runners, give amd64 and arm64 runners different tags and use them in jobs.
On Kubernetes, pods go to any node unless the runner limits them. Set the architecture with a node selector in the runner’s config.toml, or, when node_selector_overwrite_allowed permits it, per job:
job:
variables:
KUBERNETES_NODE_SELECTOR_ARCH: 'kubernetes.io/arch=amd64'
Pick a platform with image:docker
For a multi-architecture image, image: docker: platform: chooses which platform the Docker executor pulls; on Kubernetes, use the node selector above instead:
arm-sql-job:
image:
name: super/sql:experimental
docker:
platform: arm64/v8
script: echo "Run sql tests"
Without it, the runner pulls its host’s platform. Running a platform that doesn’t match the host needs emulation registered with binfmt_misc on the host, such as the QEMU command above; without it, the job fails with exec format error. In GitLab Runner 19.1 and earlier, a mismatched platform could be silently ignored, and the container ran with the host’s architecture.
On your phone
MergeBell shows a job’s log live, so an exec format error is there as soon as the container fails, and Retry reruns the job on the free tier. A retry keeps the job’s image and runner tags, so it helps once a runner can run a matching image: a rebuilt multi-architecture image under the same tag, if the runner pulls it again, or a runner fix such as QEMU or a node selector. A new image or tag in .gitlab-ci.yml needs a new commit. More in how to retry a failed GitLab pipeline.
Frequently asked questions
What does "exec format error" mean in a GitLab CI job?
The job's container tried to run a program built for another CPU architecture. Usually the image is arm64 and the runner amd64, for example an image built on an Apple Silicon Mac, or the image is amd64-only and the job ran on an Arm64 runner. Build the image for the runner's architecture, publish a multi-architecture image, or run the job on a runner that matches.
How do I check which architectures a Docker image supports?
Run docker buildx imagetools inspect with the image's name: it lists every platform in a multi-architecture image, such as linux/amd64 and linux/arm64; unknown/unknown entries are build attestations. A single-platform image shows no platform list: add --format '{{json .Image}}' to see its architecture. In a job that does start, uname -m prints the runner's architecture: x86_64 or aarch64.
How do I build a Docker image for both amd64 and arm64?
Use docker buildx build --platform linux/amd64,linux/arm64 -t your-image --push . It needs a builder that can build both, with QEMU emulation for the architecture your machine doesn't have. Docker Desktop on a Mac includes it; on Linux, install it with docker run --privileged --rm tonistiigi/binfmt --install all.
What does image: docker: platform: do in GitLab CI?
It tells the Docker executor which platform to pull from a multi-architecture image, such as platform: arm64/v8; on Kubernetes, use a node selector instead. Without it, the runner pulls its host's platform. Running a platform that doesn't match the host needs emulation registered with binfmt_misc, or the job fails with exec format error; before GitLab Runner 19.2, a mismatched platform could be silently ignored.
How do I run a GitLab.com job on an Arm64 runner?
Add the saas-linux-small-arm64 tag to the job; medium and large Arm64 runners need Premium or Ultimate. Untagged jobs run on saas-linux-small-amd64. The job's image must include linux/arm64.
Sources
- GitLab docs — image:docker (platform)
- GitLab docs — Hosted runners on Linux (amd64 and Arm64 machine types)
- GitLab Runner docs — Kubernetes: overwrite the node selector
- Docker docs — Multi-platform builds
- GitLab docs — exec format error with security analyzers
Checked against these pages on 13 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.
Do this from your phone with MergeBell
Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.
Get MergeBell for iPhoneGet MergeBell for Android
On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.