Docker multi-platform build crashes on linux/amd64 due to Zig 0.15.2 stdlib bug under Rosetta
- Dominant language
- Zig
- Stars
- 97
- Forks
- 39
- PR merge metrics
- No merged PRs in 30d
Description
## 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:
```bash
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:
```bash
# 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)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with Dockerfile lines 85–96 and reproduce the multi-platform command on Apple Silicon. Compare the failing linux/amd64 build with native arm64 and real x86_64 results, then determine whether the issue has an actionable project change or only the documented CI workaround; the issue does not define a code-level completion condition.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, zig
- Domain
- build-system, devops
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100