Search specific term/phrase surrounded by double quotes. e.g. “deep linking”
Exclude records that contain a specific term prefixed with a minus. e.g. Android -Firebase

Android Troubleshooting

Common misconfiguration scenarios you may run into and how to resolve them.


This guide lists out some of the most common challenges we see customers run into when trying to integrate the Branch Android SDK.

To integrate the Branch Android SDK, follow the steps in our Android SDK Basic Integration guide.


Using Older Android API Versions

If you need to use an Android API version older than version 15:

  1. Use Branch Android SDK version 1.14.5

  2. Add the onStart() and onStop() methods to your app:

    override fun onStart() {
    override fun onStop() {
    protected void onStart() {
    protected void onStop() {

App Has No Application Class

If your app does not have an application class, add the following to your AndroidManifest.xml file:

<application android:name="io.branch.referral.BranchApp">

Overrunning Dex Limit

Adding additional dependencies may overrun the dex limit.

This can lead to a NoClassDefFoundError or a ClassNotFoundException.

To fix this, add the following to your build.gradle:

defaultConfig {
    multiDexEnabled true
defaultConfig {
    multiDexEnabled true

Then, add the following to your Application class and make sure it extends MultiDexApplication:

override fun attachBaseContext(base: Context?) {
protected void attachBaseContext(Context base) {


InvalidClassException, ClassLoadingError, or VerificationError

InvalidClassException, ClassLoadingError, and VerificationError are often caused by a Proguard bug.

To fix this, try using the latest Proguard version.

You can also disable Proguard optimization by using the -dontoptimize flag.

Answers Shim Module

Warnings or errors may occur if you exclude the answers-shim module.

Try adding -dontwarn** to your Proguard file.

Play Services Ads Module

The Branch Android SDK has an optional dependency on Play Services Ads for GAID matching.

Using Proguard without using this library can create issues in fetching the GAID, which happens when initializing a Branch session or Branch Events.

Try adding the following to your Proguard file to solve this issue:

-keep class {$Info getAdvertisingIdInfo(android.content.Context);

-keep class$Info {
java.lang.String getId();
boolean isLimitAdTrackingEnabled();

Link Open Error

An "Unable to open this link" error happens whenever URI Scheme redirection fails.

Make sure you do not have $deeplink_path set, or you have a $deeplink_path which your AndroidManifest.xml can accept

Stuck State

You may notice your Branch initialization get stuck in the following state: initState_ == SESSION_STATE.INITIALISING

This is often caused by Branch not having the right application context from your activity.

To avoid this, make sure you pass in your application context:

const val branchKey: String = "branch_key_here"
class CustomApplicationClass : Application() {
	override fun onCreate() {
		// Branch object initialization
		Branch.getAutoInstance(this.applicationContext, branchKey)
protected static final String branchKey = "branch_key_here";

public class CustomApplicationClass extends Application {
	public void onCreate() {

		// Branch object initialization
		Branch.getAutoInstance(this.getApplicationContext, branchKey);

Automatic Initialization

One possible error you may run into is BranchError.ERR_BRANCH_ALREADY_INITIALIZED.


The Branch Android SDK will automatically initialize when the app comes to the foreground, and the first activity to show enters the RESUMED lifecycle state. This is done as a failsafe not to miss tracking sessions.

Therefore, if you delay Branch initialization, never attempt to initialize Branch, or have the app open to activities other than the launcher activity, then the Branch Android SDK will automatically initialize.

At this point, if the app's code tries to initialize Branch (again), then the SDK will throw an error. This prevents initializing over and over again, or other potentially unexpected states.

Error Handling

If you want to delay initialization without having the Branch Android SDK self-initialize, you can do so using the approach outlined in our Advanced Features guide.

Alternatively, you can ignore the error and add the following code snippet to your callback:

if (error.errorCode == BranchError.ERR_BRANCH_ALREADY_INITIALIZED) {
    branchReferringParams_ = Branch.getLatestReferringParams()
if(error.getErrorCode() == BranchError.ERR_BRANCH_ALREADY_INITIALIZED) {
   branchReferringParams_ = Branch.getLatestReferringParams();