> Fixing 16KB Page Alignment Errors in React Native for Android

If you've recently tried to publish a React Native app to Google Play, you might have been greeted with a rejection notice about 16KB page size compliance. This requirement caught a lot of developers off guard, and the error messages aren't particularly helpful in pointing you toward a solution.

The issue comes down to how native libraries (.so files) are aligned in your APK. Devices with 16KB memory pages—which includes newer Android hardware—need these libraries aligned to 16KB boundaries. If they're aligned to the traditional 4KB, your app will either be rejected by Google Play or crash on affected devices.

Understanding the Requirement

Starting November 2025, Google Play requires all apps targeting Android 15 (API 35) or higher to support 16KB page sizes. If your app missed the initial deadline, there was an extension to May 31, 2026, but that's a one-time reprieve. After that, non-compliant updates simply won't be accepted.

Apps written purely in Java or Kotlin are already compliant—the issue only affects apps with native code. React Native apps always have native code, both from React Native itself and from any native modules you're using.

Checking If You're Affected

Before diving into fixes, verify whether your app actually has alignment issues. Build your release APK or AAB, then use Android's zipalign tool to check:

zipalign -c -P 16 -v 4 your-app.apk

If the output shows failures for any .so files, you have work to do. You can also open the APK in Android Studio's APK Analyzer (Build > Analyze APK) and look at the lib folder—the alignment column will flag problematic libraries.

For a more detailed check of individual libraries, use llvm-objdump:

llvm-objdump -p libexample.so | grep LOAD

Look for align 2**14 in the output. If you see 2**12 instead, that library is only 4KB aligned and needs to be rebuilt.

The Fix

The solution involves updating your build tools and potentially some Gradle configuration.

Update Android Gradle Plugin to 8.5.1 or higher. This version automatically handles 16KB alignment for uncompressed native libraries during packaging. In your project's android/build.gradle:

buildscript {
    dependencies {
        classpath("com.android.tools.build:gradle:8.5.1")
    }
}

You'll also need Gradle 8.7+ to support this AGP version. Check android/gradle/wrapper/gradle-wrapper.properties and update if needed:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

Update your NDK to r28 or newer. NDK r28 compiles with 16KB alignment by default. If you're specifying an NDK version in your android/build.gradle, bump it:

android {
    ndkVersion "28.0.12433566"
}

If you're stuck on NDK r27 for some reason, you can enable flexible page sizes manually by adding this to your app's android/app/build.gradle:

android {
    defaultConfig {
        externalNativeBuild {
            cmake {
                arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
            }
        }
    }
}

Third-Party Libraries

Here's where things get tricky. Your own code might build correctly, but any native module you depend on could ship pre-built .so files that aren't 16KB aligned. Common culprits include older versions of image processing libraries, SQLite wrappers, and video players.

To find which dependency is causing issues, extract your APK and check each .so file individually. You can also search your Gradle cache for the problematic AAR:

find ~/.gradle/caches/ -name "*.aar" -exec sh -c \
  'unzip -l "{}" 2>/dev/null | grep -q "\.so" && echo "{}"' \;

Then inspect the shared libraries inside each AAR. Once you identify the offending package, check if there's an updated version. Most actively maintained libraries have released 16KB-compliant versions by now.

If a library hasn't been updated and you can't switch to an alternative, you may need to fork it and rebuild the native code yourself with the correct flags. Not ideal, but sometimes necessary.

Testing Your Fix

Google provides a couple ways to verify your app works on 16KB devices. The Android Emulator supports 16KB page size system images for Android 15 and later—create an AVD with one of these images and run your app.

If you have a Pixel 8, 8a, or 9 device running Android 15 QPR1 or later, you can enable 16KB mode in Developer Options by toggling "Boot with 16KB page size." The device will reboot, and you can test your app on real hardware.

You can verify the test environment is correctly configured with:

adb shell getconf PAGE_SIZE

This should return 16384 on a 16KB device or emulator.

One More Thing

After making these changes, do a clean build. Gradle caches can hold onto old artifacts, and you want to make sure everything is freshly compiled with the new settings:

cd android && ./gradlew clean && cd ..

Then rebuild your release APK and run the alignment check again. If everything passes, you're ready to submit to Google Play.

For the full technical details, see the official Android documentation on 16KB page sizes.