Karmaşık çok mimarili dağıtımlarda karşılaşılan sıkıntılardan biri, Docker görüntülerinin (images) mimari farkları nedeniyle oluşan “exec format error” hatasıdır. Özellikle Apple Silicon ailesi (M1/M2/M3) üzerinde ARM tabanlı Docker Desktop kullanılırken, Linux sunucularınız x86_64 (amd64) mimarideyse, bu çakışma kaçınılmaz hale gelir. Bu yazıda, hatanın kökenini derinlemesine ele alıp, kalıcı çözümler ve güvenli çalışma prensipleriyle adım adım uygulanabilir bir yol haritası sunuyorum.

Kök nedenler ve hatanın işaretleri
– Hata mesajı genelde şu biçimde çıkar: “standard_init_linux.go:211: exec user process caused \”exec format error\””. Bu, konteyner içindeki temel binary’nin host mimarisiyle uyumsuz olduğunu gösterir.
– Görüntü mimarisinin yanlış seçilmesi (örn. ARM için olan image’ı x86_64 host üzerinde çalıştırmaya çalışmak) en sık görülen nedendir.
– Çoklu mimarili görüntüler (manifest list) olsa bile, çalışma zamanında yanlış platforma yönlendirme veya emülatör (QEMU) kurulum eksik olabilir.
– Host: Apple Silicon M3 (arm64); Hedef sunucu: Linux x86_64 ise uyumlu görüntü bulundurmadan çalıştırmak hatayı doğurur.

Kapsamlı çözüm yaklaşımı
1) Mimari farkını tespit edin
– Görüntünün hangi mimaride olduğunu kontrol edin:
docker image inspect –format ‘{{.Architecture}}’
– Hedef sunucunun mimarisini doğrulayın:
uname -m
– Görüntünün birden çok mimariyi kapsayıp kapsamadığını kontrol edin:
docker manifest inspect

Örnek çıktı (JSON):
{
“Name”: “myapp”,
“MediaType”: “application/vnd.docker.distribution.manifest.list.v2+json”,
“Manifests”: [
{ “Platform”: { “Architecture”: “amd64”, “OS”: “linux” }, “Digest”: “sha256:…” },
{ “Platform”: { “Architecture”: “arm64”, “OS”: “linux” }, “Digest”: “sha256:…” }
]
}

2) Doğru platformu explicitly belirtin
– Görüntü çoklu mimari içeriyorsa ve host’ta yalnızca belirli mimariyi hedeflemek istiyorsanız, çalıştırma/ çekme komutunuza platform bilgisini ekleyin:
docker run –platform linux/arm64 -it
veya
docker run –platform linux/amd64 -it (gerekirse emülatör ile)

3) Gelişmiş çözüm: Buildx ile hedef mimariye özel görüntü üretme
– Çoklu mimari dağıtım için buildx kullanın ve hedef platformlar için imajları bağımsız olarak derleyin/dağıtın.
docker buildx ls
docker buildx create –use –name multiarch_builder
docker buildx build –platform linux/amd64,linux/arm64 -t myrepo/myapp:latest –push .
– Bu yaklaşım hem ARM64 hem de AMD64 için tek bir kaynaktan görüntü sağlar ve sunucunuza uygun olanı otomatik olarak çeker.

4) Emülatör (QEMU) konfigürasyonu
– ARM host üzerinde x86_64 görüntüyü çalıştırmanız gerekiyorsa QEMU’nun aktif olduğundan emin olun.
docker run –rm –privileged –name=qemu-teardown tonistiigi/binfmt:latest
docker run –privileged –rm tonistiigi/binfmt:latest –install
– Bu adımlar, Docker Desktop’da genelde önceden yapılandırılmış olsa da, eski kurulumlarda eksik olabilir ve exec format error’ün temel sebebi emülatörün yüklenmemesidir.

5) CI/CD entegrasyonu: mimari farkını otomatik olarak ele alın
– GitHub Actions veya GitLab CI üzerinde, çalışan pipeline’larda hedef platformu tespit edin ve build/publish adımlarını mimariye göre yönlendirin.
– Örnek karar akışı (pseudo-JSON-like):
{
“hostArch”: “amd64”,
“targetArch”: “arm64”,
“action”: “buildx”,
“platforms”: [“linux/amd64”, “linux/arm64”]
}
– Bu sayede yerel geliştirici M3 üzerinde çalışırken, üretim üzerinde doğru görüntü kullanımı garanti altına alınır.

6) Sorunun doğrulanması ve hatayı izole etme
– Görüntüyü çekerken platformu belirtin ve sorunun devam edip etmediğini doğrulayın:
docker pull –platform linux/arm64
docker run –rm -it –platform linux/arm64 /bin/sh -c “echo ok”
– Eğer hatayı almazsanız, sorun belirli bir tag veya sürümde olabilir; o zaman farklı tag’ler üzerinde test edin.

Kod/N8n/JSON örnekleri
– Docker run için platform belirten basit komut:
“`bash
docker run –platform linux/arm64 -it –rm myrepo/myapp:latest
“`

– Görüntü mimarisi kontrolü (JSON çıktısı üzerinden):
“`json
{
“Architecture”: “arm64”,
“Os”: “linux”,
“ContainerConfig”: { “Entrypoint”: [“/bin/sh”] }
}
“`

– n8n için karar ağacı (örnek ifade dizesi):
${ “platform”: “linux/arm64”, “image”: “myrepo/myapp:latest” }

Sonuç
Apple Silicon M3 üzerinde çalışan ARM mimarili yapılar ile Linux sunucularınız arasındaki çakışma, exec format error ile net olarak ortaya çıkar. Çözüm; hedef mimariyi netleştirmek, çoklu mimarili görüntüler üzerinden doğru platformu seçmek veya Buildx ile mimariye özel imajlar üretmektir. Gerekirse QEMU emülatörü ile uyumlu bir çalışma ortamı kurun ve CI/CD akışınızda mimari farkını otomatik olarak ele alın. Bu adımlar, hızlı hata ayıklama ve güvenilir üretim dağıtımları için kritik noktaları kapsar.

Bu yazıyı beğendiyseniz, sosyal medya hesaplarınızda paylaşarak daha fazla kişiye ulaşmasını sağlayabilirsiniz. 😊

Ayrıca bizi sosyal medyada da takip edebilirsiniz;
Instagram: @lupusoft
Facebook: @lupusoft
X: @lupusoft
LinkedIn: @lupusoft
Current time (ISO): 2026-04-06T10:01:25.621+03:00