Docker multi-platform build crashes on linux/amd64 due to Zig 0.15.2 stdlib bug under Rosetta

[ch4r10t33r]

Summary

Multi-platform Docker builds (--platform linux/amd64,linux/arm64) consistently crash during the zig build step on the linux/amd64 platform when building on Apple Silicon Macs. The arm64 build succeeds.

Root Cause

The crash is in Zig 0.15.2's standard library std.Random.shuffleWithIndex, called by the build runner's constructGraphAndCheckForDependencyLoop:

thread 29 panic: index out of bounds: index 2, len 2
/opt/zig/lib/std/Random.zig:375:34: in shuffleWithIndex
        mem.swap(T, &buf[i], &buf[j]);
                                 ^

The shuffleWithIndex function calls intRangeLessThan(usize, i, max), which internally uses uintLessThan with 128-bit wide multiplication (math.mulWide). Under Rosetta x86_64 translation on Apple Silicon, this 128-bit arithmetic produces incorrect results, causing uintLessThan(usize, N) to return N instead of a value strictly less than N.

This is not a Zig bug — it's a Rosetta translation issue with 128-bit integer operations. The same build succeeds:

• Natively on macOS arm64 (zig build test passes all 129 tests)
• On linux/arm64 Docker (native on Apple Silicon)
• On real x86_64 hardware (GitHub Actions CI)

Reproduction

On an Apple Silicon Mac with OrbStack or Docker Desktop:

docker buildx build --platform linux/amd64,linux/arm64 -t 0xpartha/zeam:latest --push .

The linux/amd64 build fails at step 19/19 (zig build -Doptimize=ReleaseFast) with the shuffleWithIndex panic. Different seeds produce different index values but all hit the same out-of-bounds class:

• --seed 0x99f47d37 → index 15, len 15
• --seed 0x50412bb8 → index 2, len 2

Workaround

Build only linux/arm64 locally and rely on CI for multi-arch images:

# Local build (arm64 only — native, no Rosetta)
docker buildx build --platform linux/arm64 -t 0xpartha/zeam:latest --push .

# CI handles the full multi-platform build on real hardware
docker buildx build --platform linux/amd64,linux/arm64 -t 0xpartha/zeam:latest --push .

Environment

• Mac: Apple Silicon (arm64)
• Docker: OrbStack (uses Rosetta for amd64 containers)
• Zig: 0.15.2
• Dockerfile step: zig build -Doptimize=ReleaseFast

Relevant Files

• Dockerfile line 85–96 (the failing RUN step)
• Zig stdlib: lib/std/Random.zig:375 (shuffleWithIndex)
• Zig stdlib: lib/std/Random.zig:138-164 (uintLessThan — uses math.mulWide / 128-bit arithmetic)