Each section names a symptom, its cause, and the action to take.
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 APKThe 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 toolsThe 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.
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_INCOMPATIBLEThe 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_DOWNGRADEThe 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.
adb install -r, and check that no Gradle task replaced it.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.
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.
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 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 missingInstall the SDK command line tools, as described in references/setup.md. On Windows, run retrace.bat.
Ask the user which device to use, and set ANDROID_SERIAL for every adb command.
Do not guess credentials. Ask the user to sign in on the device, or switch to manual mode as described in references/journeys.md.
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.