Der Container startet nicht und meldet „exec format error“? Fast immer passt die Prozessorarchitektur des Images nicht zum Host — ARM gegen x86.
Aufwand:
ca. 20 Min.
Das Symptom
Ein Docker-Container lässt sich nicht starten und meldet exec /entrypoint.sh: exec format error oder exec format error direkt beim Start. Auf dem einen Rechner —
etwa dem Entwickler-Laptop — lief dasselbe Image tadellos, auf dem Server oder dem
Mini-Rechner scheitert es sofort.
Die „Layer 8“-Wahrheit
Ein Container ist kein plattformneutrales Wunderpaket. Das Programm darin ist für
eine ganz bestimmte Prozessorarchitektur übersetzt — für x86 (die klassischen PCs
und Server) oder für ARM (Apple-Silicon-Macs, Raspberry Pi, viele Cloud-Instanzen).
Passt diese Architektur nicht zu der des Wirtsystems, kann der Prozessor die Befehle
schlicht nicht lesen, und der Kernel bricht mit „exec format error“ ab. Dass es „auf
meinem Rechner lief“, heißt nur, dass dessen Architektur zufällig passte.
Der Aufstieg von ARM hat diesen früher seltenen Fehler alltäglich gemacht: Ein auf
dem Apple-Silicon-Mac gebautes Image landet auf einem x86-Server — und streikt. Die
Lösung ist immer, Image und Host auf dieselbe Architektur zu bringen: das Image für
die richtige Plattform ziehen, beim Bauen die Zielplattform angeben oder gleich ein
Multi-Architektur-Image erzeugen. Emulation überbrückt die Lücke im Notfall, ist aber
langsam — auf Dauer will jede Architektur ihr eigenes Image.
Die echte, verifizierte Lösung
1000 % faktenbasiert. Jeder Befehl ist real, jeder Pfad existiert. Schritt für Schritt:
1.
Die Architektur-Diskrepanz erkennen
„exec format error“ bedeutet, dass das Programm im Image für eine andere Prozessorarchitektur übersetzt wurde als die des Hosts. Der Klassiker: ein für ARM gebautes Image läuft auf einem x86-Server — oder umgekehrt ein x86-Image auf einem ARM-Rechner wie einem Apple-Silicon-Mac oder Raspberry Pi.
2.
Die Architekturen vergleichen
Die Architektur des Hosts und die des Images prüfen. Stimmen sie nicht überein, ist die Ursache gefunden:
Bei einem Multi-Architektur-Image beim Herunterladen die passende Plattform erzwingen, damit die richtige Variante geladen wird:
docker pull --platform linux/amd64 meinimage
4.
Beim Bauen die Zielplattform angeben
Wird ein Image auf einem Rechner gebaut, aber auf einem mit anderer Architektur eingesetzt, die Zielplattform beim Bauen ausdrücklich setzen — mit Buildx lassen sich sogar mehrere Architekturen auf einmal erzeugen:
Zur Not lässt sich ein Image fremder Architektur per Emulation ausführen. Das funktioniert, ist aber deutlich langsamer und nur eine Übergangslösung — für den Dauerbetrieb gehört ein Image der passenden Architektur her.
Häufige Fragen (FAQ)
?Der Container läuft auf meinem Rechner, auf dem Server nicht. Warum?
Weil die Prozessorarchitekturen verschieden sind. Ein auf einem Apple-Silicon-Mac gebautes Image ist arm64, ein typischer Server erwartet amd64. Der Fehler exec format error bedeutet wörtlich: Diese Datei enthält Maschinenbefehle, die dieser Prozessor nicht kennt. Es ist kein Fehler in Ihrem Programm.
?Wie baue ich ein Image, das auf beiden Architekturen läuft?
Mit buildx und der Angabe mehrerer Zielplattformen, etwa linux/amd64 und linux/arm64. Docker legt dann ein Multi-Architektur-Image an, und die Gegenstelle zieht sich automatisch die passende Variante. Der Bau dauert länger, dafür verschwindet die Frage nach der Architektur dauerhaft.
Belege
Diese Seite ist gegen die folgenden Primärquellen geprüft – Hersteller, Standard oder Gesetzestext. Wer es nicht glaubt, muss es nicht: Da steht, wo es nachzulesen ist.