> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting — Android

> Solutions for common Primer Checkout Android issues

## 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:

```kotlin theme={"dark"}
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](https://dashboard.primer.io) 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:

```kotlin theme={"dark"}
// 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()`:

```kotlin theme={"dark"}
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      |

<Warning>
  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.
</Warning>

## Debugging tips

### Log checkout state changes

```kotlin theme={"dark"}
LaunchedEffect(checkout) {
    checkout.state.collect { state ->
        Log.d("PrimerCheckout", "State: $state")
    }
}
```

### Log all checkout events

```kotlin theme={"dark"}
PrimerCheckoutSheet(
    checkout = checkout,
    onEvent = { event ->
        Log.d("PrimerCheckout", "Event: $event")
        when (event) {
            is PrimerCheckoutEvent.Success -> { }
            is PrimerCheckoutEvent.Failure -> {
                Log.e("PrimerCheckout", "diagnosticsId: ${event.error.diagnosticsId}")
            }
        }
    },
)
```

## Getting help

When contacting Primer support, include:

1. The `diagnosticsId` from any error callbacks
2. Your Android API level, Compose version, and SDK version
3. Steps to reproduce the issue

```kotlin theme={"dark"}
onEvent = { event ->
    when (event) {
        is PrimerCheckoutEvent.Failure -> {
            Log.e("Checkout", "diagnosticsId: ${event.error.diagnosticsId}")
        }
    }
}
```

## See also

<CardGroup cols={2}>
  <Card title="Events guide" icon="bolt" href="/checkout/primer-checkout/configuration/events">
    Event handling patterns
  </Card>
</CardGroup>