Docker Build Passes Locally (M2 Mac) But Fails in GitHub Actions

The Problem

docker build worked fine on my MacBook M2. GitHub Actions CI failed immediately:

exec /usr/local/bin/node: exec format error

The container wouldn't even start.

What Happened

My M2 Mac builds for arm64 (Apple Silicon architecture) by default. GitHub Actions runners are linux/amd64. The image I built locally couldn't run on the CI runner.

The Fix

Added --platform flag to force amd64 build in CI:

# .github/workflows/ci.yml
- name: Build Docker image
  run: docker build --platform linux/amd64 -t myapp:${{ github.sha }} .

For multi-arch support (build once, run anywhere):

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
 
- name: Build multi-platform
  uses: docker/build-push-action@v5
  with:
    context: .
    platforms: linux/amd64,linux/arm64
    push: true
    tags: myregistry/myapp:latest

Root Cause

Never noticed this before because the old codebase used FROM node:14 which had a multi-arch manifest, so the exact same tag worked on both architectures. The new custom base image was only built for arm64.

Rule: always specify --platform linux/amd64 in CI, or build multi-arch from the start.