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

> Common issues and solutions for the Primer Checkout SDK

<Warning>
  Primer Checkout Android SDK is currently in **beta** (v3.0.0-beta.4).
  The API is subject to change before the stable release.
</Warning>

## Installation issues

### Compose version conflict

**Problem**: 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

**Problem**: `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

**Problem**: `PrimerPaymentMethods` shows 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`.

### Card form fields not appearing

**Problem**: Some card form fields (cardholder name, billing address) don't appear.

**Explanation**: Fields are configured by your Primer Dashboard settings. Only fields marked as required in the Dashboard will appear in the form. This is expected behavior.

### 3DS challenge not completing

**Problem**: Payment gets stuck during 3DS authentication.

**Solution**: Ensure your app's Activity has `android:configChanges="orientation|screenSize"` to prevent the WebView from being destroyed during configuration changes.

## Compose-specific issues

### Recomposition causes re-initialization

**Problem**: Checkout reinitializes on every recomposition.

**Solution**: Use `rememberPrimerCheckoutController()` which survives recomposition. Don't create the controller inside conditionals or callbacks:

```kotlin theme={"dark"}
// Correct
val checkout = rememberPrimerCheckoutController(clientToken)

// Incorrect - creates new controller on recomposition
val checkout = PrimerCheckoutController(clientToken) // Don't do this
```

### State not updating in UI

**Problem**: UI doesn't reflect state changes.

**Solution**: Use `collectAsStateWithLifecycle()`:

```kotlin theme={"dark"}
val state by checkout.state.collectAsStateWithLifecycle()
```

## Getting help

If you encounter an issue not covered here:

1. Check the error's `diagnosticsId` in logs
2. Verify your configuration in the Primer Dashboard
3. Contact Primer support with the `diagnosticsId`

## Next steps

<CardGroup cols={2}>
  <Card title="Best Practices" icon="star" href="/docs/checkout/primer-checkout/configuration/best-practices">
    Production-ready tips
  </Card>

  <Card title="First Payment" icon="credit-card" href="/docs/checkout/primer-checkout/first-payment">
    Verify your integration
  </Card>
</CardGroup>