Docker exec format error는 실행 파일의 형식이나 CPU 아키텍처가 실행 환경과 맞지 않을 때 나타나는 오류다. Apple Silicon에서 만든 이미지를 x86 서버에 배포하거나, ARM64 이미지에 AMD64 실행 파일을 복사했을 때 먼저 의심할 부분이다. 해결의 출발점은 옵션 추가가 아니라 호스트, 이미지, 이미지 내부 실행 파일의 아키텍처를 각각 확인하는 것이다.
📌 핵심 요약
- 배포 서버와 이미지가 같은 플랫폼인지 먼저 확인한다.
- 이미지 정보가 맞아도 COPY로 넣은 실행 파일의 아키텍처는 다를 수 있다.
- 배포 대상이 하나면 단일 플랫폼, AMD64와 ARM64가 함께 있으면 멀티플랫폼 빌드를 검토한다.
--platform은 대상 플랫폼을 지정한다. 기존 바이너리를 자동 변환하지는 않는다.
1. Docker exec format error 발생 위치부터 구분하기
같은 오류 문구라도 빌드 중인지, 컨테이너 시작 시점인지에 따라 확인 순서가 달라진다. RUN 단계에서 실패하면 빌더의 외부 아키텍처 실행 지원을 살피고, 배포 직후 실패하면 선택된 이미지와 시작 명령을 먼저 확인한다.
- 빌드 로그 확인: 어떤 Dockerfile 단계와 명령에서 실패했는지 기록한다.
- 시작 로그 확인:
docker logs 컨테이너명으로 문제가 된 실행 경로를 찾는다. - 시작 설정 확인: 이미지의
ENTRYPOINT와CMD가 무엇을 실행하는지 확인한다.
docker logs my-container
docker image inspect my-app:latest --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}'
위 이름은 실제 컨테이너명과 이미지 태그로 바꿔 사용한다. 이미지 내부의 셸은 실행되는데 애플리케이션만 실패한다면, 이미지 전체보다 해당 실행 파일에 원인이 있을 가능성이 높다.
Docker 공식 문서는 컨테이너 내부 코드가 실행 호스트 아키텍처와 호환돼야 한다고 설명한다. linux/amd64 이미지를 ARM64 호스트에서 실행하려면 에뮬레이션 같은 별도 지원이 필요하다. 컨테이너로 포장했다는 사실만으로 CPU 명령어 차이가 사라지지는 않는다.
근거: Docker 공식 문서 「Multi-platform builds」, 2026년 11월 확인.
1. Docker exec format error 발생 위치부터 구분하기

2. 호스트 CPU와 이미지 아키텍처 확인 명령
로컬 컴퓨터의 CPU와 실제 Docker 엔진이 실행되는 서버의 CPU는 다를 수 있다. 원격 Docker context를 사용한다면 로컬 터미널의 uname -m만으로 배포 환경을 판단하지 않는 것이 중요하다.
# 현재 연결 대상 확인
docker context show
# Docker 서버의 OS와 아키텍처 확인
docker info --format '{{.OSType}}/{{.Architecture}}'
# Linux 호스트에서 직접 확인할 때
uname -m
# 레지스트리에 게시된 이미지의 플랫폼 확인
docker manifest inspect --verbose registry-user/my-app:latest
# 로컬에 저장된 이미지 확인
docker image inspect my-app:latest --format '{{.Os}}/{{.Architecture}}'
x86_64는 Docker 플랫폼 표기에서 보통 amd64, aarch64는 arm64에 대응한다. 표기 문자열이 다르다는 이유만으로 불일치라고 판단하지 말고, 같은 CPU 계열인지 해석해야 한다.
docker manifest inspect --verbose는 레지스트리 이미지의 플랫폼 정보를 확인하는 명령이다. 로컬에서만 만든 이미지라면 docker image inspect를 사용한다. 두 명령의 확인 대상이 다르므로, 로컬 빌드 결과와 레지스트리에 남아 있는 이전 태그를 혼동하지 않아야 한다.
멀티플랫폼 이미지에는 플랫폼별 이미지를 가리키는 목록이 들어 있다. Docker는 이미지를 가져올 때 실행 환경에 맞는 변형을 선택하므로, 동일한 태그 아래에 필요한 플랫폼이 실제로 게시됐는지가 핵심이다.
근거: Docker 공식 CLI 문서 「docker manifest」의 플랫폼 조회 설명 및 「Multi-platform builds」의 이미지 선택 원리.
2. 호스트 CPU와 이미지 아키텍처 확인 명령 바로가기
3. 이미지 내부 바이너리와 ENTRYPOINT 점검하기
이미지 메타데이터가 linux/arm64여도 내부의 모든 파일이 ARM64라는 뜻은 아니다. Dockerfile에서 개발 컴퓨터의 빌드 산출물을 COPY했다면, AMD64 실행 파일이 ARM64 이미지에 들어갈 수 있다.
이때는 실행에 실패한 파일 자체를 검사한다. Linux 환경에서 file 명령을 사용할 수 있다면 다음처럼 CPU 계열과 파일 형식을 확인한다.
# 빌드 산출물 확인
file ./app
# ELF 실행 파일의 헤더 확인
readelf -h ./app
file 출력에 x86-64가 나타나면 AMD64 계열, ARM aarch64가 나타나면 ARM64 계열로 해석할 수 있다. 검사 도구가 설치돼 있지 않다면 별도 진단 환경에서 확인한다. 컨테이너가 시작되지 않아도 docker create와 docker cp로 파일을 꺼낼 수 있다.
docker create --name inspect-app my-app:latest
docker cp inspect-app:/app/app ./app-from-image
docker rm inspect-app
file ./app-from-image
/app/app은 실제 실행 파일 경로로 바꾼다. 위 절차는 컨테이너 프로세스를 시작하지 않으므로, 시작 단계에서 오류가 나는 이미지의 파일을 조사할 때 유용하다.
실행 파일이 셸 스크립트라면
CPU 정보가 일치하면 스크립트 첫 줄의 shebang과 인터프리터 경로를 확인한다. 예를 들어 #!/bin/sh로 시작하는지, 지정한 셸이 이미지에 존재하는지 점검한다. Windows에서 편집했다면 CRLF 줄바꿈도 함께 살핀다.
실행 권한과 인터프리터 누락은 별도 오류로 나타날 수도 있다. 따라서 모든 시작 실패를 아키텍처 문제로 묶기보다, 실제 오류 문구와 파일 형식을 함께 보는 편이 정확하다.
3. 이미지 내부 바이너리와 ENTRYPOINT 점검하기
4. buildx --platform으로 단일·멀티플랫폼 빌드 선택하기
배포 대상이 AMD64 서버뿐이라면 AMD64 이미지 하나를 정확하게 만드는 것으로 충분하다. ARM64 개발 컴퓨터를 쓴다는 이유만으로 운영 이미지까지 반드시 멀티플랫폼으로 만들 필요는 없다.
| 배포 환경 | 빌드 대상 | 확인 기준 |
|---|---|---|
| AMD64 서버만 운영 | linux/amd64 |
실행 파일과 네이티브 라이브러리의 AMD64 지원 |
| ARM64 서버만 운영 | linux/arm64 |
베이스 이미지와 의존성의 ARM64 지원 |
| 두 CPU 계열에 동일 태그 배포 | linux/amd64,linux/arm64 |
플랫폼별 이미지 게시 및 각각의 실행 검증 |
먼저 현재 빌더가 지원하는 플랫폼을 확인한다. --platform을 생략하면 기본 대상은 BuildKit 데몬의 플랫폼이므로, 개발 환경이 바뀌면 의도와 다른 이미지가 만들어질 수 있다.
docker buildx inspect --bootstrap
# AMD64 단일 플랫폼을 빌드해 로컬 이미지 저장소로 가져오기
docker buildx build --platform linux/amd64 -t my-app:amd64 --load .
# AMD64와 ARM64 이미지를 레지스트리에 게시하기
docker buildx build --platform linux/amd64,linux/arm64 -t registry-user/my-app:latest --push .
레지스트리 이름과 태그는 실제 게시 권한이 있는 경로로 바꾸고 로그인한 뒤 실행한다. 멀티플랫폼 배포 예시는 --push로 게시까지 진행한다. 로컬 저장소와 빌더 구성에 따라 로드 지원이 달라지므로, --push를 무조건 --load로 바꾸지는 않는다.
빌드 대상 지정과 실행 파일 생성은 별개의 작업이다. 이미 만들어진 AMD64 바이너리를 복사하는 Dockerfile이라면 ARM64 대상 빌드에서도 그 파일은 그대로 들어간다. 대상별로 컴파일하거나, 대상 아키텍처에 맞는 배포 파일을 선택하도록 빌드 과정을 수정해야 한다.
근거: Docker Buildx 공식 문서 「docker buildx build」의 --platform, --load, --push 설명.
4. buildx --platform으로 단일·멀티플랫폼 빌드 선택하기
5. QEMU 에뮬레이션과 네이티브 빌드 선택 기준
Docker가 안내하는 멀티플랫폼 빌드 전략은 3가지다. QEMU 에뮬레이션, 여러 네이티브 노드, 멀티스테이지 빌드를 활용한 교차 컴파일이다. 2026년 11월 확인한 공식 문서도 이 구분을 사용한다.
QEMU는 시작하기 편하지만 컴파일과 압축 작업에서 크게 느려질 수 있다. 공식 문서가 공통 배속이나 절감률을 제시하지는 않으므로, “몇 배 느리다”는 숫자를 모든 프로젝트에 적용할 근거는 없다. 실제 빌드 시간은 같은 소스와 캐시 조건으로 측정해야 한다.
운영 관점에서는 빌드가 성공하는지와 반복 배포 비용을 나눠 판단하는 것이 합리적이다. 가끔 만드는 이미지라면 에뮬레이션으로 충분할 수 있지만, 컴파일 시간이 배포를 지연시키면 네이티브 빌더나 교차 컴파일을 검토할 이유가 생긴다.
Go처럼 대상 OS와 아키텍처를 지정할 수 있는 도구 체인은 교차 컴파일 후보가 된다. 다만 C 라이브러리나 네이티브 모듈에 의존한다면 대상용 툴체인과 라이브러리까지 필요할 수 있다. 플랫폼 옵션 하나로 모든 의존성 문제가 해결된다고 가정하지 않는 것이 중요하다.
근거: Docker 공식 문서 「Multi-platform builds」의 빌드 전략과 QEMU 성능 제약 설명.
buildkit-qemu-* 바이너리 누락으로 오류가 날 수 있다고 안내한다. 이 경우 공식 BuildKit 릴리스의 바이너리를 BuildKit이 실행되는 호스트의 PATH에 설치하는 절차를 확인한다. 외부 아키텍처 실행에 필요한 QEMU의 binfmt_misc 등록도 점검 대상이며, Docker Desktop에는 기본 등록돼 있다.
5. QEMU 에뮬레이션과 네이티브 빌드 선택 기준 조회하기
6. 배포 전 exec format error 재발 방지 체크리스트
빌드 성공만으로 배포 호환성이 증명되지는 않는다. 이미지 목록에 대상 플랫폼이 있고, 그 이미지 내부의 실행 파일이 맞으며, 실제 대상 환경에서 시작되는지까지 확인해야 점검이 끝난다.
- 실제 배포 서버의 OS와 CPU 계열을 확인했는가?
- 게시한 태그에 필요한 플랫폼 이미지가 포함돼 있는가?
- COPY한 실행 파일과 네이티브 의존성이 대상 아키텍처에 맞는가?
- ENTRYPOINT 스크립트의 첫 줄, 줄바꿈, 실행 권한을 확인했는가?
- AMD64와 ARM64를 함께 배포한다면 각 환경에서 시작 및 주요 기능을 검증했는가?
- 태그 재사용으로 이전 이미지가 실행되지 않았는지 이미지 ID나 다이제스트를 확인했는가?
재발 방지의 핵심은 빌드 환경의 기본값에 배포 대상을 맡기지 않는 것이다. CI에 --platform을 명시하고, 외부에서 내려받거나 복사하는 실행 파일도 같은 대상 기준으로 선택하면 원인을 추적하기 쉬워진다.
Docker exec format error가 나타나면 호스트, 이미지, 내부 실행 파일 순서로 일치 여부를 확인한다. 그다음 실제 배포 대상에 맞춰 단일 플랫폼 또는 멀티플랫폼 빌드를 선택하면, 불필요한 재빌드를 줄이면서 해결 지점에 도달할 수 있다.
출처: Docker 공식 문서 「Multi-platform builds」, 「docker manifest」, 「docker buildx build」 및 Moby BuildKit 공식 저장소 「docs/multi-platform.md」. 문서 확인 기준: 2026년 11월. 본문의 진단 순서와 배포 선택 기준은 이 문서들을 바탕으로 정리한 실무적 해석이다.