agent verified the upgrade on arm64 but production runs x86 - a native module failed at deploy

TL;DR

The agent tested on arm64 but production is x86, and the native module shipped the wrong binary. Test on the production architecture in CI (multi-arch matrix or x86 runners) and make sure native modules resolve the right prebuilt binary per platform.

Error

agent verified the upgrade on arm64 but production runs x86  -  a native module failed at deploy

Steps

1. Confirm the architecture mismatch: check the failing module's binary architecture and the production machine's architecture. Expected output: The module binary is arm64 and production is x86 (or vice versa).

2. Reproduce on the production architecture: run the install and tests on an x86 runner or container. Expected output: The failure reproduces where production runs.

3. Fix the resolution: ensure the package manager fetches the x86 prebuilt binary (platform-specific optional deps, correct install flags) or builds from source on x86. Expected output: The module installs the correct binary for x86.

4. Add the production architecture to the CI matrix for dependency-bump PRs. Expected output: Architecture mismatches fail in CI, not at deploy.

5. Document the production architecture in the agent's environment notes so verification targets it by default. Expected output: The agent tests where the code will run.

When to use

• A native module fails at deploy after passing tests elsewhere
• Dev machines and production run different CPU architectures
• You are adding multi-arch coverage to CI

When not to use

• Pure-language packages with no native code; architecture is irrelevant
• Failures from OS version rather than CPU architecture; check the libc and OS
• Emulation layers (Rosetta, qemu) masking the issue; test on real hardware or real containers

Variant phrasings

native module failed at deploy, wrong architecture

tested on arm64 but production is x86

multi-arch CI for dependency upgrades

Why it happens

Native modules ship per-architecture binaries, and the package manager picks the binary for the machine doing the install. The agent's arm64 machine got an arm64 binary, which is correct there and useless on x86 production.

Edge cases

• Universal binaries can hide the mismatch until a specific code path runs; do not trust a passing import as proof.
• Building from source on x86 needs a toolchain in the deploy image; prebuilts are usually the better fix.
• Docker's platform emulation can silently run the wrong arch in CI; pin the runner platform explicitly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xVHFa1dtYQZIehQZ06lmEw