isar community fails on 16 KB page size Android images (even with legacy packaging enabled)

[JakobLichterfeld]

Steps to Reproduce

Using a Android Emulator with an image of Type 16 KB Page Size Google APIs PlayStore and Using legacy packaging as suggested by Google results in the following exception:

IsarError (IsarError: Could not initialize IsarCore library for processor architecture "android_arm64". If you create a Flutter app, make sure to add isar_flutter_libs to your dependencies.
Invalid argument(s): Failed to load dynamic library 'libisar.so': dlopen failed: empty/missing DT_HASH/DT_GNU_HASH in "/data/app/<redacted>/lib/arm64/libisar.so" (new hash type from the future?))

without legacy packaging the app fails to install on those images.

(Other images without 16KB page size run fine)

Code sample

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:isar/isar.dart';
import 'package:path_provider/path_provider.dart';

void main() {
  final dir = await getApplicationDocumentsDirectory();
  final isar = await Isar.open(
    [UserSchema],
    directory: dir.path,
  );

  runApp(const MainApp());
}

class MainApp extends StatelessWidget {
  const MainApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(
        body: Center(
          child: Text('Hello World!'),
        ),
      ),
    );
  }
}

Details

• Platform: Android Emulator with an image of Type 16 KB Page Size Google APIs PlayStore
• Flutter version: 3.27.3
• Isar-community version: 3.1.8

---

• I searched for similar issues already
• I filled the details section with the exact device model and version
• I am able to provide a reproducible example

[JakobLichterfeld]

Updating:

• Gradle to 8.7
• AGP to 8.6.1
• KGP to 2.1.0

didn't help as well

[JakobLichterfeld]

This seems to be related with a potential fix: getsentry/sentry-dart#2237

The page sizes are aligned for our Android dependency, but we need to check Isar and SQLite dependencies.

And

I updated our sample app to support 16kb pages by bumping NDK to 27 and updating the app/build.gradle as described in here . I works on a 16KB emulator device, also with our Isar and SQFlite packages.  

-> https://developer.android.com/guide/practices/page-sizes#compile-r27

[JakobLichterfeld]

No success with:

android {
  ...
  ndkVersion = "28.0.12916984"
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
      }
    }
  }
}

[pamafe1976]

Hi. Any news on this one?

[ZhuJHua]

Isar is written in rust and is introduced into Android through native libraries, so it is useless to modify ndk in Android project. You need to use the latest cargo-ndk to build rust into so file.

[ZhuJHua]

I made a fork supprot android 16kb pagesize which is based on the official version of isar version 4.0.0-dev.14 ：
Just use

  isar_flutter_libs:
    git:
      url: https://github.com/ZhuJHua/isar
      path: packages/isar_flutter_libs

[JakobLichterfeld]

Starting November 1st, 2025, all new apps and updates to existing apps submitted to Google Play and targeting Android 15+ devices must support 16 KB page sizes.

Source: https://android-developers.googleblog.com/2025/05/prepare-play-apps-for-devices-with-16kb-page-size.html

--> @vicenterusso we really need to fix the 16 KB page size for version 3 and 4

[smiera]

this is a huge problem. any updates?

[JakobLichterfeld]

Upstream Issue: isar#1699

[dcarv001]

Migration Guide: Supporting 16 KB Page Size for Isar on Android

Note: This guide was developed through an intensive five-hour investigation, with significant assistance from ChatGPT. While it successfully addressed my use case, your environment may differ. Treat this tutorial as a proof of concept—please run your own tests, adapt the steps as needed, and report any feedback or issues you encounter.

Quick-Fix Warning: This approach is an urgent, stopgap solution intended to address the immediate 16 KB page-size issue. It’s critical that the maintainers of both the Isar and Isar Community repositories review this change and adapt it properly into the official codebase.

1. Clone Your Exact Isar Version

# Replace `v3.1.8` with the version you're using (IMPORTANT, CLONE THE VERSION YOU ARE USING)
git clone --branch v3.1.8 https://github.com/isar-community/isar.git
cd isar

2. Edit Cargo Config for Android Targets

Open:

packages/isar_core_ffi/.cargo/config.toml

Add '"-C", "link-arg=-Wl,-z,max-page-size=16384"' under each target.* section:

[target.aarch64-linux-android]
rustflags = [
  "-C", "link-arg=-Wl,--hash-style=both",
  "-C", "link-arg=-Wl,-z,max-page-size=16384"
]

[target.armv7-linux-androideabi]
rustflags = [
  "-C", "link-arg=-Wl,--hash-style=both",
  "-C", "link-arg=-Wl,-z,max-page-size=16384"
]

[target.x86_64-linux-android]
rustflags = [
  "-C", "link-arg=-Wl,--hash-style=both",
  "-C", "link-arg=-Wl,-z,max-page-size=16384"
]

[target.i686-linux-android]
rustflags = [
  "-C", "link-arg=-Wl,--hash-style=both",
  "-C", "link-arg=-Wl,-z,max-page-size=16384"
]

What it does:

The flag -Wl,-z,max-page-size=16384 tells the linker to align all loadable segments to a maximum page size of 16 384 bytes (16 KB), matching Android 15+ requirements.

3. Build the Native Libraries via cargo ndk

Inside isar_core_ffi directory, run:

cargo ndk \
  -t aarch64-linux-android \
  -t armv7-linux-androideabi \
  -t x86_64-linux-android \
  -t i686-linux-android \
  --platform 23 \
  -o ../packages/isar_flutter_libs/android/src/main/jniLibs \
  build --release

• cargo ndk: Wrapper that uses the Android NDK toolchain to compile Rust crates for Android ABIs.

• Output goes to:

  packages/isar_flutter_libs/android/src/main/jniLibs/
    ├─ arm64-v8a/libisar_core.so
    ├─ armeabi-v7a/libisar_core.so
    ├─ x86_64/libisar_core.so
    └─ x86/libisar_core.so
  

All .so files are now aligned to 16 KB.

4. Verify Page Size Alignment

Use llvm-readelf to confirm:

$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/<platform>/bin/llvm-readelf -l \
  path/to/libisar_core.so \
  | awk '/LOAD/ { print $8 }' | sort -u

• 0x4000 → 16 KB (correct)
• 0x1000 → 4 KB (needs rework)

5. Integrate into Your Flutter Project

Manual Copy
Copy the generated jniLibs and overwrite the jniLibs/ folders in:

\~/.pub-cache/hosted/pub.dartlang.org/isar\_flutter\_libs-<version>/android/src/main/jniLibs/

6. Test

Install your app on an Android 15+ emulator/device with “Boot with 16 KB page size” enabled and verify if works.

7. Publish & Validate

1. Upload your APK/AAB to Internal Test, Alpha/Beta, or Play Store.
2. Install on a real or virtual Android 15+ device.
3. Confirm the page-size warning is gone and the app installs/runs normally.

[dcarv001]

Additional Testing & Validation Recommendations

I did not identify any hard‑coded 4 KB page‑size values in the Isar codebase. Nevertheless, migrating to 16 KB can have hidden side effects. I strongly recommend the following steps to validate the changes before updating the Isar and Isar Community versions:

• Run all existing CI/CD pipelines (e.g., GitHub Actions) without modifications to catch regressions.
• Execute unit and integration tests in isar_core and isar_core_ffi to ensure offsets, headers, and buffer logic still pass.
• Perform end‑to‑end tests on Android emulators and real devices across API levels, all ABIs, and both 4 KB and 16 KB page‑size configurations.
• Run smoke tests in Flutter apps, verifying database creation, read/write operations, migrations, and performance.
• Automate build verification, ensuring all targets compile and package correctly and that Play Store warnings are resolved.

Only thorough, repeatable testing—especially leveraging Isar’s existing CI/CD workflows—can ensure this migration introduces no unintended side effects.

[SergoFrost]

@vicenterusso , we need this, it is very important for our society 🙏