Troubleshooting Guide

Causes: Binary not installed or not in PATH

Solutions:

1. Verify installation:

   which mkapk

2. If empty, reinstall:

   dpkg --install ./mkapk-aarch64.deb

3. Check permissions:

   chmod +x $PREFIX/bin/mkapk

Solution: Install OpenJDK 21

apt install openjdk-21 -y

Then verify:

java -version

Solution: Add execute permission to binary

chmod +x $PREFIX/bin/mkapk

Cause: Project not initialized

Solution: Initialize project first

mkapk init

Then configure config.json with your project settings.

Cause: SDK_ROOT or TARGET_SDK incorrectly configured

Solution: Fix config.json

{
  "SDK_ROOT": "/path/to/android-sdk",
  "TARGET_SDK": "34"
}

Verify the path exists:

ls ~/android-sdk/platforms/android-34/android.jar

Cause: Native linking error (missing symbols, wrong ABI)

Solutions:

1. Check for missing dependencies in EXTRA_FLAGS:

   "EXTRA_FLAGS": ["-lm", "-ldl"]

2. Verify all source files are included
3. Check C++ flags are correct:

   "EXTRA_FLAGS": ["-std=c++17", "-fexceptions"]

Cause: Keystore issues (wrong password, missing alias, corrupted file)

Solutions:

1. For debug builds, mkapk creates debug.keystore automatically
2. For release, verify keystore exists:

   keytool -list -v -keystore ~/my-release.keystore

3. Check config.json KEYSTORE_ALIAS matches actual alias
4. If corrupted, recreate keystore (this will invalidate old signatures)

Cause: Native library missing or wrong ABI

Solutions:

1. Verify library compiled for correct ABI:

   file lib/arm64-v8a/libmylib.so

2. Match device ABI:

   adb shell getprop ro.product.cpu.abi

3. Build for correct ABI:

   mkapk build -arch aarch64-linux-android

4. Check library is included in APK:

   unzip -l MyApp.apk | grep .so

Solution: Clean and rebuild

mkapk clean
mkapk build

This resets the incremental build cache.