Troubleshooting

Each section names a symptom, its cause, and the action to take.

A command reports a usage error

The command exits with 2 and prints a line that starts with Error:, such as an unknown option or a missing value. Print the usage of the command, and fix the command line with the options that the usage lists:

java -jar "$R8_ASSISTANT_JAR" instrument --help

instrument refuses the APK

The APK is neither debuggable nor signed only with the debug key. Only instrument the debug build, never the release APK. Never change the release signing config of the project for this.

instrument finds no build tools

The SDK has no build-tools version with aapt2, zipalign and apksigner, or instrument does not find the SDK. Run the commands from the project root, so that instrument reads sdk.dir from local.properties, or set ANDROID_HOME. Install build tools as described in references/setup.md.

The project signs debug builds with its own keystore

instrument signs with the default debug keystore, so the instrumented APK does not install over the debug build, and instrumented tests do not run against it. Pass the keystore of the project:

java -jar "$R8_ASSISTANT_JAR" instrument \
  --input app/build/outputs/apk/debug/app-debug.apk \
  --output app/build/r8-assistant/app-debug-instrumented.apk \
  --ks app/debug.keystore \
  --ks-pass env:DEBUG_KEYSTORE_PASSWORD \
  --ks-key-alias debug

INSTALL_FAILED_UPDATE_INCOMPATIBLE

The installed app has another signature, for example a build from an app store or a build signed with another key. Ask the user before you uninstall it, because uninstalling deletes the data of the app:

adb uninstall com.example.app

INSTALL_FAILED_VERSION_DOWNGRADE

The installed app has a higher version code. For a debuggable installed app, install with adb install -r -d. Otherwise ask the user before you uninstall the app.

No log file on the device

  • The installed APK is not the instrumented one. Install it again with adb install -r, and check that no Gradle task replaced it.
  • The path uses another application ID. Check the ID of the installed APK, as described in references/setup.md.
  • The device runs API level 15 or lower, which gets no log.
  • No app code made a reflective call before the pull. Run the journey further, or treat the journey as one without reflection.

Empty or short log

No app code reflected during the journey, the reflection happened inside ignored code (see the limits in references/capture.md), or the app restarted and truncated the log. An empty log is no evidence for deleting a rule. Mark the rules of that journey as uncovered unless another journey covers them.

Events from earlier steps are missing

A new app process truncated the log: the app restarted, a second process started, or a test runner started a process per test. Split the journey at the restart and pull the log before each restart.

A request line has no result line

The call threw, or the process died before the call returned. Find the exception in logcat. In a debug log, this is often expected behavior of the app, such as probing for an optional class.

The crash has no matching log event

The reflection runs inside androidx., kotlin. or kotlinx. code, or in code that the journey did not reach in the debug build. Write the rule from the retraced stack trace, as described in references/rules.md.

retrace is missing

Install the SDK command line tools, as described in references/setup.md. On Windows, run retrace.bat.

Several devices are connected

Ask the user which device to use, and set ANDROID_SERIAL for every adb command.

A flow needs a login or other private input

Do not guess credentials. Ask the user to sign in on the device, or switch to manual mode as described in references/journeys.md.

The release build fails in R8

Read the R8 error. Missing class warnings come from the rules or the dependencies of the project, not from this skill. Fix them before continuing, and never add -dontwarn for classes that the app uses at runtime.