Android Issues

This page covers Android-specific issues you may encounter when integrating ZETIC Melange.

JNI Library Loading Failure

Symptoms:

• java.lang.UnsatisfiedLinkError: dlopen failed
• java.lang.UnsatisfiedLinkError: couldn't find native library
• App crashes immediately on ZeticMLangeModel initialization

Cause: The native C++ NPU driver libraries are not being extracted correctly from the APK.

Solution:

Add useLegacyPackaging to your app-level build.gradle:

android {
    ...
    packagingOptions {
        jniLibs {
            useLegacyPackaging true
        }
    }
}

android {
    ...
    packaging {
        jniLibs {
            useLegacyPackaging = true
        }
    }
}

After adding this, perform a clean build (Build then Clean Project, then Rebuild Project).

Build Configuration Issues

Minimum SDK Version

Symptom: Build fails with SDK version incompatibility.

Solution: Ensure your minSdkVersion is 24 or higher:

android {
    defaultConfig {
        minSdkVersion 24
    }
}

ProGuard / R8 Rules

Symptom: App crashes in release builds but works in debug.

Solution: If you use code shrinking, ensure the Melange classes are preserved. Add to your proguard-rules.pro:

-keep class com.zeticai.mlange.** { *; }

Network and Download Issues

Symptom: Model initialization fails with network errors.

Solutions:

• Ensure the device has internet connectivity. The SDK downloads the model binary on first use.
• Check that your app has the INTERNET permission in AndroidManifest.xml:

  <uses-permission android:name="android.permission.INTERNET" />

• If behind a corporate firewall, ensure access to Melange API endpoints is not blocked.

Emulator Limitations

Symptom: Inference runs but performance is unexpectedly slow, or NPU fallback messages appear in logs.

Cause: Android emulators do not have NPU hardware.

Solution: Always test on a physical device for accurate performance results. The emulator will use CPU fallback, which is significantly slower.

Threading Issues

Symptom: NetworkOnMainThreadException or UI freezes during model initialization.

Solution: Initialize and run models on a background thread:

lifecycleScope.launch(Dispatchers.IO) {
    val model = ZeticMLangeModel(this@MainActivity, PERSONAL_KEY, MODEL_NAME)
    val outputs = model.run(inputs)

    withContext(Dispatchers.Main) {
        // Update UI
    }
}

Still Having Issues?

• Check Common Errors for cross-platform issues
• Visit the FAQ
• Join the Discord community
• Email contact@zetic.ai