Zig "incompatible zig version" (0.13 vs 0.14) in CI

Zig has no stable language guarantee yet, so build scripts and manifests are tied to a compiler version. A project built for 0.14 fails on a 0.13 runner (or the reverse) because the build API and manifest fields differ.

What this error means

zig build fails with a version error such as "your zig version ... does not meet the minimum build requirement" or a parse error in build.zig.zon, after the runner installed a different minor than the project targets.

error: your zig version (0.13.0) does not meet the minimum build requirement of 0.14.0

Common causes

The runner installed a different Zig minor

CI pinned or defaulted to a Zig version that does not match what build.zig and build.zig.zon were written against. The pre-1.0 API changes between minors.

build.zig.zon fields differ across versions

Manifest fields and the build API (for example dependency hashing) changed between 0.13 and 0.14, so the wrong compiler cannot parse or run the build.

How to fix it

Pin the exact Zig version the project targets

1. Read the version the project expects from build.zig.zon or its README.
2. Pin that exact version in the setup step.
3. Re-run so build.zig and the manifest match the compiler.

- uses: mlugg/setup-zig@v1
  with:
    version: 0.14.0

Update build.zig and the manifest for the new minor

If you intend to move to a newer Zig, migrate the build script and manifest fields to that version rather than mixing them.

How to prevent it

• Pin an exact Zig version in CI, not a floating one.
• Bump build.zig and build.zig.zon together when changing minors.
• Document the supported Zig version in the repository.

Related guides