Troubleshooting and SDK errors (iOS)
This page covers errors from the Components SDK (WeavrComponents). Its newer asynchronous methods surface errors as cases of a typed result enum, each carrying a traceability value that helps our support team debug an issue; the deprecated completion-based overloads still surface errors through ErrorResponse objects or module-specific enums. For errors from the Push ProvisioningPush ProvisioningA method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta. SDK, see its own Troubleshooting page.
Traceability
Every result returned by the Components SDK's asynchronous public interfaces carries a traceability value of type Traceability, alongside the outcome itself, whether it's a success or a failure. It exposes two properties:
| Property | Description |
|---|---|
sessionId | Identifies the app session. Stays the same for as long as the app is not terminated. |
operationId | Identifies the specific operation that produced the result, for example a single biometrics login, KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. flow, or initialization attempt. |
If you run into an error that isn't self-explanatory, or one you can't resolve, share the sessionId and operationId from the traceability value with our support team, along with the steps to reproduce the issue. This lets us locate the relevant logs on our end and diagnose the root cause much faster than a description of the symptoms alone.
Initialize components
UXComponents.initialize(environment:uiKey:) is asynchronous and returns an InitializationResult. Its error cases are:
| Case | Description |
|---|---|
serverError(code:message:traceability:) | The server rejected the request. Can retry the initialisation. |
networkFailure(cause:traceability:) | A network error occurred. Can retry the initialisation. |
setupError(cause:error:traceability:) | A local setup error occurred, for example a keychain failure. |
failure(cause:traceability:) | An unexpected error occurred. |
The deprecated completion-based initialize(env:uiKey:completion:) and initialize(environment:uiKey:completion:) overloads return an ErrorResponse whose code contains one of these WeavrErrorCode values:
| Error Code | Description | Integer Code |
|---|---|---|
cantSetUIKey | Unable to set UI keyUI keyA public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. during initialization. | 1001 |
cantSetSecureFieldsLength | Unable to set secure fields length. | 1002 |
cantRecreateKeyPairs | Unable to recreate key pairs. | 1003 |
cantEnableSecurityService | Unable to enable security service. | 1004 |
cantRetrieveSecurityServiceKey | Unable to retrieve security service key. | 1005 |
Set user token
UXComponents.setUserToken(token:) is asynchronous and returns an AssociateTokenResult. Its error cases are:
| Case | Description |
|---|---|
serverError(code:message:traceability:) | The server rejected the token, e.g. it's invalid or has expired. |
networkFailure(cause:traceability:) | The device couldn't reach the server. Retry once connectivity is restored. |
failure(cause:traceability:) | An unexpected error occurred. |
The deprecated completion-based setUserToken(token:, completion:) returns an ErrorResponse where code is one of:
- HTTP status codes: set by
DataResponseErrorduring token validation or API communication failures. -1: local or precondition failure (for example, UI keyUI keyA public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. not set).
Common HTTP status codes
| Error Code | Description |
|---|---|
| 400 | Bad request. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
| 409 | Conflict. |
| 412 | Precondition failed. |
| 429 | Too many requests. |
| 5xx | Server error (500, 502, 503, 504, and others). |
Update FCM token
UXComponents.psa.updateFCMToken(_:) is asynchronous and returns an UpdateFCMTokenResult. Its error cases are:
| Case | Description |
|---|---|
notReadyForEnrollment(traceability:) | The programmeProgrammeA programme represents your application within Weavr. Everything you create - customers, instruments, and transactions - sits beneath a programme. When you register as an Embedder, you receive a programme in the Sandbox and, once approved, one in Production. does not support biometrics, or it's not properly set up. |
serverError(code:message:traceability:) | The server rejected the request. Retry, e.g. on the next app launch or before enrolling the user. |
networkError(cause:traceability:) | The device couldn't reach the server. Retry once connectivity is restored. |
failure(cause:traceability:) | An unexpected error occurred. |
The deprecated UXComponents.psa.updateDeviceToken returns an ErrorResponse where code is one of:
- HTTP status codes: as specified by the server.
-1: local or precondition failure (for example, missing UI keyUI keyA public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. or device fingerprint).
Common HTTP status codes
| Error Code | Description |
|---|---|
| 400 | Bad request. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
| 409 | Conflict. |
| 412 | Precondition failed. |
| 429 | Too many requests. |
| 5xx | Server error (500, 502, 503, 504, and others). |
Start biometric enrollment
UXComponents.psa.startEnrollment returns a BiometricsEnrollmentResult representing the outcome of the enrollment flow. This enum can be any case of:
| Case | Description |
|---|---|
completed | The enrollment flow completed successfully. |
initialisationError(error:) | The SDK was not properly initialized when the enrollment flow was triggered. The associated error value is a BiometricsInitializationError specifying what went wrong. |
cryptographyError(error:) | An error occurred in the cryptography module while attempting to create the enrollment. The associated error value is a BiometricsCryptographyError specifying what went wrong. |
failedBiometricsChallenge | The user failed the biometrics challenge. |
unauthorized | The token provided is not authorized. Log the user in again and provide a new token. |
userDoesNotConsent | The user did not consent to enroll by tapping the cancel button. |
failedToLoadBrand | The flow failed to launch because the biometrics configuration could not be fetched. |
noPhoneNumberAvailable | The user does not have an associated phone number. |
noBiometricsAvailable(hardwareSupportsBiometrics:) | Biometrics are not available on the device. If hardwareSupportsBiometrics is true, Face ID or Touch ID is not enrolled but the device supports it. If false, the device does not support any biometrics. |
challengeFailed(cause:) | The enrollment challenge failed. For example, the OTP expired or an invalid value was provided. The associated cause string describes the reason. |
Start biometric login
UXComponents.psa.startBiometricLogin(viewController:) is asynchronous and returns a BiometricsLoginResult. Its error cases are:
| Case | Description |
|---|---|
userEnteredInvalidFallbackPassword(code:message:traceability:) | The user's fallback password was wrong. code can reflect a lockout after too many attempts, in which case fall back to standard password login. |
userDeclinedChallenge(traceability:) | The user cancelled the OS biometric prompt. This isn't an error - dismiss the flow quietly and let them use standard login instead. |
cryptoError(error:message:status:traceability:) | The device's local key material is broken or missing, e.g. after a device restore. The user needs to re-enroll biometrics. |
serverError(code:message:traceability:) | The server rejected the request. |
networkFailure(cause:traceability:) | The device couldn't reach the server. Retry once connectivity is restored. |
failure(cause:traceability:) | An unexpected error occurred. |
The deprecated startBiometricPSALogin(completion:), startBiometricPSALogin(completion:onForgotPasscode:), and completion-based startBiometricLogin(completion:) return an ErrorResponse where code is one of:
- HTTP status codes: set by
DataResponseErrorduring biometric login, verification, or association API calls. -1: local failures (for example, biometric authentication failures, crypto errors, or missing UI state).
Common HTTP status codes
| Error Code | Description |
|---|---|
| 400 | Bad request. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
| 409 | Conflict. |
| 412 | Precondition failed. |
| 429 | Too many requests. |
| 5xx | Server error (500, 502, 503, 504, and others). |
Common local failures
- Biometric authentication failed (for example, Face ID or Touch ID rejected)
- Cryptographic operation errors
- Missing UI keyUI keyA public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. or initialization state
- Device biometric capability unavailable
Start biometric SCA challenge
UXComponents.psa.startBiometricsChallenge provides a BiometricsChallengeResult in a completion callback. BiometricsChallengeResult includes a state property that defines the challenge state once the method completes.
The state can be any of:
| State | Description |
|---|---|
completed | Challenge completed successfully. |
declined | Challenge declined by the user. |
noSessionAvailable | No session was present when the challenge was initiated. |
invalidPassword | The user failed the biometrics check, and introduced an invalid password in the password fallback. |
failedToDisplay(message: String) | Couldn't display the biometrics challenge. Includes a message with an internal reason. |
cryptoError(message: String) | An error occurred in the cryptography module. Includes a message with an internal reason. |
serverError(flow: BiometricsChallengeFlow, error: ErrorResponse) | There was an unexpected error while communicating with the server. The BiometricsChallengeFlow enum identifies in which part of the biometrics flow the error occurred, and the error specifies the code and message obtained. |
Start know-your-customer flow
UXComponents.kyc.startKyc reports errors through the KYCEvent.kycError callback, which includes a KYCErrorCause value describing the failure.
| Error Cause | Description |
|---|---|
initializationError | KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. initialization failed. |
failedToCheckIfTermsAndConditionsAccepted | Failed to check whether the user already accepted the terms and conditions. |
failedToGetTermsAndConditions | Failed to load the terms and conditions for the user to accept. |
failedToAcceptTermsAndConditions | Failed to record the user's acceptance of the terms and conditions. |
failedToLoadKYC | Failed to load the KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. details while initializing the flow. |
invalidParameters | Invalid parameters provided to the KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. flow. |
unauthorized | User is not authorized to perform KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers.. |
applicantNotFound | The applicant could not be found. |
applicantMisconfigured | The applicant is misconfigured in the system. |
networkError | Network connection error during KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. process. |
unexpectedError | An unexpected error occurred that doesn't fit other categories. |
userDismissedFlow | The user dismissed the KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. UI before the verification flow completed. |
Installation and build issues
The following issues aren't SDK errors returned at runtime - they show up during installation or at build/launch time.
App crashes at launch with "Library not loaded" for a Weavr framework
This entry applies to both WeavrComponents and WeavrPushProvisioning when installed via CocoaPods.
Symptom: your app builds and links without errors, but crashes immediately on launch (before any of your code runs) with a dyld error such as:
dyld[...]: Library not loaded: @rpath/WeavrComponents.framework/WeavrComponents
Referenced from: <...> /YourApp.app/YourApp
Reason: tried: '.../YourApp.app/Frameworks/WeavrComponents.framework/WeavrComponents' (no such file)
The same failure can occur for WeavrPushProvisioning.framework. This typically shows up on projects that also ship an app extension (for example, a Wallet ExtensionWallet ExtensionAn iOS app extension that integrates an issuer app with Apple Wallet. The UI Wallet Extension provisions a card from the issuer app into Wallet (the in-app provisioning flow). The Non-UI Wallet Extension exposes the issuer's card-management actions (such as 'View card details') from inside Wallet itself. Apple requires both for a primary issuer-app integration.) that statically links one of our frameworks which your main app target also depends on.
Cause: starting with WeavrComponents 3.8.1 and WeavrPushProvisioning 2.0.1, both frameworks use Apple's mergeable libraries feature (MERGEABLE_LIBRARY = YES) so they can be statically linked into an app extension. For WeavrComponents, this also avoids a SwiftUICore linker error that occurred because it depends on SwiftUI; WeavrPushProvisioning has no SwiftUI dependency, so that error doesn't apply to it. A side effect of adopting mergeable libraries is that the framework's binary carries a newer Mach-O load command (LC_ATOM_INFO) that CocoaPods uses ruby-macho to inspect when deciding whether a vendored xcframework needs to be embedded in a given target. CocoaPods versions that bundle ruby-macho older than 4.1.0 (this includes CocoaPods 1.16.x and earlier) can't parse that load command, silently treat the framework as static, and skip generating the "Embed Pods Frameworks" step for it - even for your main app target, and even though the framework is still linked. The framework compiles and links fine; it's just never copied into the app bundle, so dyld can't find it at runtime.
Fix: pin a CocoaPods version whose ruby-macho dependency understands LC_ATOM_INFO (CocoaPods 1.17.0+, which depends on ruby-macho ~> 4.1.0). Add a Gemfile at your project root if you don't already have one:
source 'https://rubygems.org'
gem 'cocoapods', '>= 1.17.0'
Then install and use it explicitly:
bundle install
pod install
If you already run pod install through Bundler (a Gemfile and Gemfile.lock are the standard way CocoaPods versions are pinned for an iOS project), just bump the cocoapods version and re-run bundle install. Running a bare pod install against a global CocoaPods gem older than 1.17.0 reproduces the issue even if your Gemfile is correct, so make sure CI and every developer machine call pod install through bundle exec.
This doesn't affect Swift Package Manager installs - SPM doesn't go through this CocoaPods detection step at all.