Troubleshooting — Android

Quick diagnosis

Symptom	Likely Cause	Solution
Compose version conflict	Compiler version mismatch	Align `kotlinCompilerExtensionVersion`
Checkout stays in Loading	Invalid/expired client token	Check Logcat for errors, regenerate token
Payment methods empty	Dashboard misconfiguration	Verify Dashboard settings and client session fields
Recomposition causes re-init	Controller created outside `remember`	Use `rememberPrimerCheckoutController()`
State not updating in UI	Not using lifecycle-aware collect	Use `collectAsStateWithLifecycle()`

Installation issues

Compose version conflict

Cause: Build fails with Compose compiler version mismatch. Solution: Ensure your Compose compiler version is compatible:

android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.8"
    }
}

Runtime issues

Checkout stays in Loading state

Cause: PrimerCheckoutState.Loading never transitions to Ready. Possible causes:

Invalid or expired client token
Network connectivity issues
Incorrect API key in client session creation

Solution: Check Logcat for error messages from the SDK. Ensure your client token is fresh and generated correctly.

Payment methods not showing

Cause: PrimerPaymentMethods shows an empty list. Possible causes:

No payment methods configured in Primer Dashboard
Client session missing required fields
Payment methods not enabled for the currency/country

Solution: Verify your Primer Dashboard configuration and ensure your client session includes the correct currencyCode and countryCode.

3DS challenge not completing

Cause: Payment gets stuck during 3DS authentication. Solution: Ensure your Activity has android:configChanges="orientation|screenSize" to prevent the WebView from being destroyed during configuration changes.

Compose-specific issues

Recomposition causes re-initialization

Cause: Checkout reinitializes on every recomposition. Solution: Use rememberPrimerCheckoutController() which survives recomposition:

// Correct
val checkout = rememberPrimerCheckoutController(clientToken)

// Incorrect - creates new controller on recomposition
val checkout = PrimerCheckoutController(clientToken)

State not updating in UI

Cause: UI doesn’t reflect state changes from the SDK. Solution: Use collectAsStateWithLifecycle():

val state by checkout.state.collectAsStateWithLifecycle()

Validation vs payment errors

Understanding the difference helps with proper error handling:

Error Type	When It Occurs	How It’s Handled
Validation errors	During input (invalid format, missing fields)	Handled automatically by input components; prevents form submission
Payment failures	After form submission (declined card, network issues)	Requires explicit handling with error container or custom code

Don’t confuse these two error types. Validation errors prevent form submission and are shown inline. Payment failures occur after the form is submitted and require explicit handling.

Debugging tips

Log checkout state changes

LaunchedEffect(checkout) {
    checkout.state.collect { state ->
        Log.d("PrimerCheckout", "State: $state")
    }
}

Log all checkout state changes

val state by checkout.state.collectAsStateWithLifecycle()

LaunchedEffect(state) {
    Log.d("PrimerCheckout", "State: $state")
    when (val s = state) {
        is PrimerCheckoutState.Success -> { }
        is PrimerCheckoutState.Failure -> {
            Log.e("PrimerCheckout", "diagnosticsId: ${s.error.diagnosticsId}")
        }
        else -> Unit
    }
}

Getting help

When contacting Primer support, include:

The diagnosticsId from any PrimerCheckoutState.Failure
Your Android API level, Compose version, and SDK version
Steps to reproduce the issue

val state by checkout.state.collectAsStateWithLifecycle()

LaunchedEffect(state) {
    val s = state
    if (s is PrimerCheckoutState.Failure) {
        Log.e("Checkout", "diagnosticsId: ${s.error.diagnosticsId}")
    }
}

Events guide

Event handling patterns

​Quick diagnosis

​Installation issues

​Compose version conflict

​Runtime issues

​Checkout stays in Loading state

​Payment methods not showing

​3DS challenge not completing

​Compose-specific issues

​Recomposition causes re-initialization

​State not updating in UI

​Validation vs payment errors

​Debugging tips

​Log checkout state changes

​Log all checkout state changes

​Getting help

​See also

Events guide

Quick diagnosis

Installation issues

Compose version conflict

Runtime issues

Checkout stays in Loading state

Payment methods not showing

3DS challenge not completing

Compose-specific issues

Recomposition causes re-initialization

State not updating in UI

Validation vs payment errors

Debugging tips

Log checkout state changes

Log all checkout state changes

Getting help

See also