UniFFI checksum mismatch on armeabi-v7a Android builds (115 Sentry users)

[nbradbury]

Summary

uniffi.wp_api.IntegrityCheckingUniffiLib.<clinit> throws RuntimeException: UniFFI API checksum mismatch on a subset of Android devices in production, almost exclusively 32-bit armeabi-v7a split APKs. The embedded Kotlin-side checksums don't match the checksums queried from the packaged native .so at load time.

Sentry impact (last 90 days, version alpha-2026-04-20):

• JETPACK-ANDROID-1G48: 49 users / 538 events
• WORDPRESS-ANDROID-3EZ1: 66 users / 315 events

Combined: 115 users. Affected devices include Galaxy A02 (SM-A022F), Redmi 6, and similar 32-bit ARM hardware. Once <clinit> fails the JVM caches the failure, so every subsequent call to anything in uniffi.wp_api throws NoClassDefFoundError — that's why per-user event counts are high.

Note: This JPAndroid draft PR attempted to resolve the problem by catching the LinkageError, but the real source of the problem is in this repo.

Reproduction stack trace

ExceptionInInitializerError
  at uniffi.wp_mobile.WpService$Companion.wordpressCom-E0BElUM(wp_mobile.kt:8016)
  at uniffi.wp_mobile.UniffiLib.<clinit>(wp_mobile.kt:906)
  at uniffi.wp_api.Wp_apiKt.uniffiEnsureInitialized(wp_api.kt:6571)
Caused by: RuntimeException: UniFFI API checksum mismatch: try cleaning and rebuilding your project
  at uniffi.wp_api.Wp_apiKt.uniffiCheckApiChecksums(wp_api.kt:4388)
  at uniffi.wp_api.IntegrityCheckingUniffiLib.<clinit>(wp_api.kt:867)

Investigation findings

1. UniFFI bindgen reads from the host .so, not the Android .so

native/kotlin/build.gradle.kts (around lines 34-35):

val nativeLibraryPath =
    "$cargoProjectRoot/target/release/lib${rustPrimaryModule}${getNativeLibraryExtension()}"

That path resolves to the host-built library (Linux x86_64 on Buildkite), produced by cargoBuildLibraryRelease which runs cargo build --package wp_mobile --release without a --target flag. generateUniFFIBindings in native/kotlin/api/kotlin/build.gradle.kts passes this path as --library <nativeLibraryPath> to wp_uniffi_bindgen generate. So the Kotlin checksums are baked from the host binary, then validated at runtime against the per-ABI Android .so files shipped in the AAR.

For this to work correctly, UniFFI checksums must be identical across compilation targets. They aren't, for armeabi-v7a.

2. The 5 Android build agents run independently, with no pinned Rust toolchain

.buildkite/pipeline.yml (introduced/parallelized in #1203) runs:

• rust-build-host — 1 agent, host .so
• rust-build-android — 4 parallel agents (matrix: arm, arm64, x86, x86_64), each via .buildkite/build-android-rust-target.sh

.buildkite/build-android-rust-target.sh installs Rust on each agent with:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -v -y

No rust-toolchain.toml exists at the repo root, so each agent independently resolves whatever stable channel rustup considers current at the moment its job runs. Across 5 parallel agents on different machines, with no shared cache, this introduces drift.

3. Why specifically armeabi-v7a

The crash hits 32-bit ARM almost exclusively. arm64-v8a devices do not crash. The pattern points to target-pointer-width-sensitive divergence:

• usize/isize are 32-bit on armeabi-v7a and i686, 64-bit elsewhere.
• The host (Linux x86_64) and arm64-v8a both have 64-bit usize, so their UniFFI checksums tend to match.
• If any function in the UniFFI interface includes usize (directly or via a transitive type), the proc-macro emits a checksum that differs between 32-bit and 64-bit targets.
• wp_api/src/ has usize in 4 files: themes.rs, wp_com/domains.rs, login/url_discovery.rs, wp_com/sites.rs. Worth auditing each to see whether usize appears in any #[uniffi::export] or #[derive(uniffi::Record)] surface (directly or via a public re-exported type).
• Android x86 (also 32-bit) would in theory be affected too but doesn't show up in Sentry because Android x86 devices are essentially extinct in the field.

4. No prior tracking issue

Searched this repo for checksum, armeabi, abi (issues + PRs); only #1199 is loosely related (XCFramework snapshots, not Android). PR #1203 "Speed up Android CI builds" is the most likely point of introduction since it split a previously-single-agent build across 5 agents.

Suggested fixes

Two layers — both worth landing:

A. Generate Kotlin bindings from an Android .so (root cause)

Change nativeLibraryPath in native/kotlin/build.gradle.kts to point at one of the cross-built Android .so outputs (arm64-v8a is the safe choice — matches host pointer width, supermajority of users). Update the dependency in native/kotlin/api/kotlin/build.gradle.kts (generateUniFFIBindings.dependsOn) and the artifact-download in .buildkite/publish-wp-api-kotlin.sh accordingly.

This alone shifts the reference target but doesn't make ABIs agree with each other — that's fix B.

B. Eliminate target-pointer-width sensitivity (defense in depth)

1. Pin the Rust toolchain. Add rust-toolchain.toml at the repo root:

   [toolchain]
   channel = "1.83.0"   # or current team standard
   targets = [
     "aarch64-linux-android",
     "armv7-linux-androideabi",
     "i686-linux-android",
     "x86_64-linux-android",
   ]

   rustup honors this automatically, so all 5 Buildkite agents resolve to the same version regardless of when their job runs.

2. Audit usize/isize in the UniFFI surface. Anywhere usize/isize appears in a #[uniffi::export] function, #[derive(uniffi::Record)] field, or public type used through FFI, replace with explicit u32/u64. Start with the 4 files identified above.

C. CI gate (recommended)

Add a publish-time check that loads each per-ABI .so and compares its uniffi_checksum_* exports against the values embedded in the published Kotlin bindings. Fail the publish step on any mismatch.

Verification plan

1. Locally reproduce the mismatch:
   • cargo build --release (host)
   • cargo build --release --target armv7-linux-androideabi (needs cargo-ndk)
   • nm -D target/release/libwp_mobile.so | grep uniffi_checksum > host.txt
   • nm -D target/armv7-linux-androideabi/release/libwp_mobile.so | grep uniffi_checksum > v7.txt
   • diff host.txt v7.txt — if non-empty, the hypothesis is confirmed.
2. Apply fix A, regenerate bindings against the arm64-v8a .so, repeat the symbol diff between bindings-reference and armeabi-v7a.
3. If still divergent, fix B (usize audit) is required, not optional.
4. After upstream fix lands and a new alpha is published, the Android app bumps wordpress-rs, installs on a 32-bit ARM emulator or Galaxy A02 / Redmi 6 from device farm, verifies no crash.

Why the report on this project specifically

We've been tracking these two Sentry issues for weeks; the data is unambiguous about the affected ABI. Happy to provide additional Sentry breadcrumbs, raw event samples, or coordinate on a fix branch — let me know what would help.

[nbradbury]

Here's a separate plan Claude came up with for resolving this:

plan-wordpress-rs-uniffi-fix-2026-05-13.pdf

[oguzkocer]

Investigation Report: UniFFI Checksum Mismatch

What we did

We investigated the runtime UniFFI API checksum mismatch crash affecting 115 users on WPAndroid 26.6 and 26.7 (Sentry issues JETPACK-ANDROID-1G48 and WORDPRESS-ANDROID-3EZ1).

We built a validation script (add/uniffi-checksum-validation branch) that:

1. Downloads published rs.wordpress.api:kotlin and rs.wordpress.api:android artifacts from S3
2. Extracts the expected checksum values from the Kotlin sources JAR
3. Extracts the actual checksum return values from each ABI's .so via disassembly
4. Compares them per ABI (armeabi-v7a, arm64-v8a, x86, x86_64)

We also downloaded the actual device-specific APK from Play Console (Samsung Galaxy A13, which appears in Sentry crash data) and compared the DEX bytecode checksum constants against the .so in the split APK.

---

What we found

1. Published S3 artifacts have matching checksums across all ABIs

We tested four published versions:

Version	Result
efb7f56d (pre-#1203, before parallel CI)	PASS (789/789)
9edcee43 (26.6 — crashes in production)	PASS (756/756)
4fac42b1 (26.7 — crashes in production)	PASS (808/808)
09dd8d55 (latest trunk at time of testing)	PASS (1045/1045, with 1 extraction artifact)

All checksum function return values match between the Kotlin sources JAR and every ABI's .so in the AAR.

2. Device APK artifacts also match

For the Galaxy A13 (SM-A135F) device-specific split APK of version 26.7 (versionCode 1488):

• The libwp_mobile.so in config.armeabi_v7a.apk is byte-for-byte identical to the .so in the S3 AAR
• We extracted 734 checksum constants from the DEX bytecode in base.apk using dexdump and compared them against the .so checksum function return values: zero mismatches, zero missing functions

3. No usize on the UniFFI surface

The issue hypothesized that usize (which is 32-bit on armeabi-v7a, 64-bit on arm64) in UniFFI-exported types could cause pointer-width-dependent checksum divergence. We audited all usize usages in wp_api/src/, wp_mobile/src/, and wp_mobile_cache/src/:

• All usize in wp_api/ is in #[cfg(test)] functions or module-private methods
• wp_mobile/ uses usize internally but converts to u64 at the UniFFI boundary (e.g., SyncResult::new casts usize to u64)
• wp_mobile_cache/ uses usize only for internal DB operations, never exported through UniFFI

We also confirmed this empirically: building the host library and cross-compiling for armv7-linux-androideabi with the same toolchain produces identical checksum values across all 1071 checksum functions.

4. Galaxy A13 receives armeabi-v7a split APK despite being arm64-capable

The SM-A135F (Galaxy A13) is an arm64-v8a device, but Play Store delivers config.armeabi_v7a.apk for it. This means the crash is not limited to 32-bit-only hardware — it affects arm64 devices running 32-bit native code.

5. Rust toolchain drift is not the cause

The issue hypothesized that parallel Buildkite agents with unpinned Rust toolchains could produce different checksums. While the lack of rust-toolchain.toml is a real gap, it cannot explain the crashes because:

• The published artifacts have matching checksums (tested above)
• Local builds with the same toolchain produce identical checksums across targets

6. JNA is 5.18.1 across all affected versions

JNA version is constant at 5.18.1 for 26.6, 26.7, and current trunk. The libjnidispatch.so in the device APK matches the official Maven Central JNA 5.18.1 artifact (same BuildID, same symbols — the APK copy is just stripped).

---

Theories considered and status

Theory	Status	Reasoning
Rust toolchain drift across CI agents	Eliminated	Published artifacts have matching checksums
usize pointer-width divergence	Eliminated	No usize on UniFFI surface; same-toolchain cross-compilation produces identical checksums
Code version drift (host vs Android builds)	Eliminated	Checksums match in published artifacts
Corrupted APK / Play Store delivery	Eliminated	Device APK .so is byte-for-byte identical to S3 artifact
Split APK version mismatch across updates	Not testable	No install/update timing data in Sentry
JNA/libffi short return value corruption on 32-bit ARM	Not testable from artifacts	Checksums are Short (16-bit) returned in ARM r0 (32-bit register). If JNA/libffi mishandles sub-word return values on specific devices, the comparison would fail at runtime even though the .so contains the correct value. Mozilla Bug 1992149 documents a similar pattern: JNA crashes on armeabi-v7a only, with BAD_FFI_TYPEDEF, in a Rust/UniFFI/JNA stack, partially resolved by a JNA update.
Device-specific runtime issue (native lib caching, memory corruption, Mediatek SoC quirk)	Not testable from artifacts	Would explain why artifacts match but devices crash

---

What we cannot explain

The published artifacts and the actual device APK all have matching checksums. The crash is real (538 events, 49 users on Jetpack alone), but we cannot reproduce the mismatch from any artifact we can access. The mismatch must occur at runtime on specific devices.

---

Recommended next step

Instrument the crash to capture what actually happens at runtime. Add diagnostic logging in WPAndroid (in or around WpServiceProvider) that captures:

• Build.SUPPORTED_ABIS
• Which specific checksum function fails
• The expected value vs the actual value returned by the native function
• PackageInfo.splitNames (to confirm split APK delivery)
• App version history on the device (was the app recently updated?)

This data would tell us whether it's a JNA marshalling issue (wrong value returned), a stale native lib (function missing or from old version), or something else entirely.