How to handle NDK crashes

Julius Kato Mutumba

October 17, 2022

In this post, we’ll look at how to handle NDK crashes when using Nutrient Android SDK.

What is NDK?

The Android NDK(opens in a new tab) is a native development kit, and it allows you to develop Android apps using C/C++.

Here at Nutrient, the largest percentage of our codebase is written in C++. This helps us control the performance of our SDK and share code across the multiple platforms we support. However, it also increases the chances of a crash happening at the native level.

NDK crash

When a native crash happens in your application, the crash logs won’t contain fully readable symbol names, but you’ll get a list of addresses that point to the location where the crash happened, similar to this:

pid: 1656, tid: 1656, name: crasher  >>> crasher <<<
signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr --------
    r0 00000000  r1 00000678  r2 00000006  r3 f70b6dc8
    ip 00000006  sp ff96ad18  lr f700ced5  pc f700dc98  cpsr 400b0010
backtrace:
    #00 pc 00042c98  libc.so
    #01 pc 00041ed1  libc.so
    #02 pc 00018d35  libpspdfkit.so
    #03 pc 00000f21  libpspdfkit.so
    #04 pc 00016795  libpspdfkit.so
    #05 pc 00000abc  libpspdfkit.so

Sometimes the logs can look very different depending on the nature of the crash, but always look out for libpspdfkit.so to be sure that the Nutrient library is involved in the crash.

Symbolicating native crashes

To make sense of these logs, you’ll need to convert them to a human-readable <source-file>:<line-number> format, which is done via a process called symbolication(opens in a new tab).

You can follow the steps below to symbolicate a crash log.

1 — Go to the Nutrient Portal(opens in a new tab) and download the unstripped native library symbols.

2 — Use the ndk-stack(opens in a new tab) tool of your local NDK as follows:

cat crash.dump | ndk-stack -sym PSPDFKit-for-Android-NDK-Debugging-Symbols-<version>/<arch>

Since symbols are different for each Nutrient version and CPU architecture, it’s necessary to provide a path to the appropriate symbols.

You can also read the logs directly from logcat(opens in a new tab):

adb logcat | ndk-stack -sym PSPDFKit-for-Android-NDK-Debugging-Symbols-<version>/<arch>

The steps above may be enough to help you solve the problem. However, if this process doesn’t return any data, you’re probably using a mini dump from Google Breakpad(opens in a new tab). In this case, please report the crash to our support team for further assistance.

Support

When you report the crash, you’ll be asked to provide the crash logs from logcat or a native crash mini dump file and information about the Nutrient version and CPU architecture where the crash happened.

You can define the path for crash dumps via PSPDFKit#setNativeCrashDumpPath and download a mini dump from that path from your device using adb pull /path/to/crashDump, as explained in our troubleshooting guides.

These dumps are in the Google Breakpad format and are also accepted by crash reporting services like Crashlytics. Uploading these dump files to the crash analytics servers may be configured differently, depending on the service you use.

Firebase Crashlytics

To provide the full native crash dump in the Google Breakpad mini dump file format, Firebase has a specific configuration(opens in a new tab). Please make sure you follow all the steps, as it differs slightly from the usual Firebase configuration.

When you reach step 5, follow the alternative way as explained in the Upload symbols for library modules and external dependencies(opens in a new tab) section. For the unstrippedNativeLibsDir, you can download the unstripped .so files from the Nutrient Portal(opens in a new tab).

Conclusion

In this post, you saw how to handle native crashes when using Nutrient Android SDK. If you have more questions about native crash handling, feel free to contact us on Support, and we’ll be happy to help.