Installation issues
Swift Package Manager fails to resolve
Problem: Xcode reports that it cannot resolveprimer-sdk-ios, or the package gets stuck while resolving versions.
Solution: Confirm the package URL is https://github.com/primer-io/primer-sdk-ios.git and that the dependency rule targets the 3.0.0-beta.8 beta. Then reset Xcode’s cached package state:
- File ▸ Packages ▸ Reset Package Caches
- File ▸ Packages ▸ Resolve Package Versions
The Primer Checkout iOS SDK requires iOS 15.0+. If your target’s deployment version is lower, SPM cannot satisfy the platform requirement and resolution fails.
CocoaPods: bundle code-signing error on Xcode 14
Problem: Afterpod install, the build fails with an error stating that a resource bundle needs to be code signed.
Solution: Add the following post_install script to your Podfile, then run pod install again. It disables code signing on the SDK’s resource bundles, which do not require signing:
Podfile, always run pod install again and reopen the generated .xcworkspace rather than the .xcodeproj.
See the Installation guide for the full setup steps.
Runtime issues
Checkout stays in the initializing phase
Problem:PrimerCheckoutSession.phase never transitions from .initializing to .ready, so your composable views show only the loading state.
Possible causes:
Solution: When initialization fails, the session delivers a
.failure with a PrimerError through the onCompletion closure on .primerCheckoutSession(_:theme:onCompletion:). Inspect that error and log its diagnosticsId:
Checkout fails at start with an invalid-value error
Problem: The checkout shows the error screen right away, oronCompletion receives a .failure whose PrimerError has errorId invalid-value. The description names the key paymentHandling.
Cause: PrimerSettings(paymentHandling: .manual). Primer Checkout creates the payment itself and does not support manual payment handling.
Solution: Use the default .auto. To pass an idempotency key or to abort a payment before the SDK creates it, set onBeforePaymentCreate. See PrimerPaymentHandling.
Payment methods not showing
Problem: No payment methods appear, or a payment method you enabled is missing from the list. If no method is available, the session never reaches.ready, PrimerPaymentMethods renders nothing, and onCompletion receives a .failure. Its PrimerError has errorId misconfigured-payment-methods or missing-configuration.
Possible causes:
- No payment methods are configured in the Primer Dashboard.
- The client session is missing required fields.
- Payment methods are not enabled for the requested currency or country.
- The payment method is not supported by Primer Checkout on iOS. Primer Checkout hides payment methods it cannot present.
- Klarna is missing. Primer Checkout lists Klarna only if your app adds the
PrimerKlarnaSDKpod. See the Installation guide. Adyen Klarna does not need it.
currencyCode and countryCode. Primer filters payment methods server-side based on these values, and the SDK then keeps only the methods it supports. If Primer returns no payment methods, checkout fails with misconfigured-payment-methods. If Primer Checkout supports none of the returned methods, checkout fails with missing-configuration.
Card form fields not appearing
Problem: Some card form fields — such as cardholder name or billing address fields — do not appear inPrimerCardForm.
Explanation: The visible fields are driven by your Primer Dashboard configuration, surfaced through the session’s published state. Each default field building block self-hides unless its field is present in that configuration, so only fields enabled in the Dashboard appear. This is expected behavior, not a bug.
3DS challenge not completing
Problem: A payment gets stuck during 3D Secure authentication. Solution: 3DS is handled automatically by the SDK. Make sure you do not dismiss or recreate the hosting view while the challenge is on screen — tearing down the view tears down the session (see below). The SDK does not apply its own timeout to the payment, so it keeps waiting while the challenge is on screen. A challenge that fails arrives like any other failed attempt: a.failure(error, checkoutData) in onCompletion (SwiftUI) or primerCheckoutPresenterDidFailWithError(_:checkoutData:) (UIKit). The payment was created before the challenge started, so checkoutData carries its payment id. See the Handle payment result guide.
SwiftUI-specific issues
Session re-created on every render
Problem: Checkout reinitializes repeatedly, flickering back to.initializing, because a new PrimerCheckoutSession is allocated each time the view’s body is evaluated.
Solution: Own the session with @StateObject so SwiftUI keeps a single instance across re-renders. Never construct it inline in body, inside a conditional, or in a callback:
UI not updating
Problem: Your custom slot content does not reflect changes such as validation errors, surcharge updates, or the loading state. Solution: The Primer composable views observe their session’s@Published state automatically — you do not need a manual subscription. Drive your custom UI by reading from the session state inside the slot closure:
@State or copying its values into local variables breaks observation — always read session.state at the point of use.
Getting help
If you encounter an issue not covered here:- Capture the
diagnosticsIdfrom thePrimerErrordelivered inonCompletion(SwiftUI) orprimerCheckoutPresenterDidFailWithError(_:checkoutData:)(UIKit). - Verify your configuration in the Primer Dashboard.
- Contact Primer support and include the
diagnosticsIdso the team can trace your request.
See also
Installation
Add the SDK via SPM or CocoaPods
Handle Payment Result
Process success, failure, and dismissal
Primer Error
Inspect errors and the diagnosticsId
Checkout Session
Own and observe the session lifecycle