Error Handling
There is a manifold of error scenarios which can occur during the initialisation or usage of the Nevis Mobile Authentication SDK. This chapter serves to provide an overview of the most prominent or usual error scenarios as well as our recommendation on how to handle them. As every app has different requirements, the specifics are up to the customer app developers as well as the business requirements of the app itself.
The chapter will not list all errors, just the most prominent ones. Refer to the API documentation for the complete set.
SDK initialization errors
Errors during SDK initialization are grouped as InitializationError java, swift, objc, flutter, react native.
These errors either require user interaction to resolve or cannot be resolved at all, rendering the app non-functional on the specific device. Additionally, due to platform differences not all errors are applicable to both platforms.
| Error | Require user interaction | Resolvable | Android | iOS |
|---|---|---|---|---|
RootedError | (✅) | ❌ | ✅ | ❌ |
DeviceProtectionError | ❌ | ❌ | ✅ | ✅ |
HardwareError | ❌ | ❌ | ✅ | ❌ |
ProtectedDataUnavailable | ❌ | ❌ | ❌ | ✅ |
LockScreenHasChangedError(*) | ✅ | ✅ | ✅ | ❌ |
NoDeviceLockError | ✅ | ✅ | ✅ | ✅ |
AppExtensionConfigurationRequired | ❌ | ❌ | ❌ | ✅ |
AppExtensionConfigurationNotInExtension | ❌ | ❌ | ❌ | ✅ |
ContainingAppInitializationRequired | ✅ | ✅ | ❌ | ✅ |
In essence, only the NoDeviceLockError can be easily resolved by user interaction. We recommend showing the user an informational message about the necessity of creating and using a device passcode to protect the phone for security reasons.
The ProtectedDataUnavailable error (which is only applicable for iOS devices) is an indication that the SDK is initialised too early in the app's lifecycle when access to the keychain is not yet possible. Generally, this error should not occur in production apps as it's an indication of not using the SDK correctly. Our recommendation is to refactor the app code to ensure the SDK is initialised later in the app's lifecycle to ensure the app is out of the prewarming phase and keychain access is available.
Alternatively, the SDK can be re-initialised in case this error occurs to retry gaining access to protected data.
The DeviceProtectionError is a catch-all initialization error raised by the tamper guards that are active in the release flavor. It does not indicate a single specific condition; any of the following can trigger it:
- The device is jailbroken (iOS) or rooted (Android).
- A debugger is attached to the process — this includes deploying a release build directly from an IDE or via the command line while a device is connected via USB (for example, using
flutter run --release, an Xcode run scheme, or Android Studio's run action). - The app is running inside a simulator or emulator.
- Dynamic instrumentation frameworks such as Frida are detected.
- The app's binary integrity check fails (checksum mismatch due to tampering).
Because the guards are intentionally obfuscated, the error gives no indication of which specific guard fired. This is by design: exposing the reason would help an attacker bypass it.
To test a release build on a real device without triggering DeviceProtectionError, distribute the build through a distribution channel that installs the app without attaching developer tooling. Suitable options are TestFlight (iOS), Firebase App Distribution (Android and iOS), or a direct APK install via adb install (Android only). See Testing release builds during development for guidance and the Troubleshooting guide for a step-by-step resolution.
All other errors either indicate a severe security issue (like using a rooted device) or a device not fulfilling the minimum security requirements (which is only applicable for Android devices).
The hardening related errors DeviceProtectionError and RootedError can also occur during operation execution as the SDKs guard network will check the mobile devices integrity during operation execution.
Removing the device lock after registration will automatically render all registered credentials invalid for OS-managed authenticators (Android biometric, Device passcode, Android fingerprint, TouchID and FaceID) as well as the iOS Application PIN and iOS Application Password . This action will require re-registration, invalidated credentials cannot be "re-enabled".
The Android Application PIN or Android Application Password authenticators are not affected.
App extension initialization errors
These initialization errors are specific to running the SDK inside an iOS app extension.
AppExtensionConfigurationRequiredis raised when the SDK is running inside an app extension but no app extension configuration was provided. An app extension configuration is mandatory when the SDK runs inside an app extension.AppExtensionConfigurationNotInExtensionis raised when an app extension configuration was provided while the SDK is not running inside an app extension. The containing application must be initialized without an app extension configuration.ContainingAppInitializationRequiredis raised when the extension is started before the containing application has ever initialized the SDK, meaning the shared data does not exist yet. The recommended handling is to prompt the user to open the main application once, then retry.
On the Objective-C surface these are reported as NMAInitializationError, with dedicated InitializationErrorType values of the same names, so they can be distinguished in a switch on errorType.
See iOS App Extensions for the full setup.
Recoverable errors
RecoverableError java, swift, objc, flutter, react native indicates that the issue can be solved during the operation via user interaction. They are mainly related to the Application PIN or Application Password authenticators except for the FingerprintUserVerificationError java, flutter, react native which is Android specific. A recoverable error will not lead to the operation directly failing as it's not considered an operation result.
Operation errors
Operation errors occur during operation execution which leads to the onError() callback being executed.
Most errors are grouped into OperationError java, swift, objc, flutter, react native or OutOfBandOperationError java, swift, objc, flutter, react native depending on the nature of the operation itself.
Depending on the underlying cause, various forms are possible:
- User interaction related errors such the user cancelling the operation or waiting for too long.
- Backend related errors such as the backend rejecting the selected user or authenticator.
- Networking related errors.
For errors who don't have a specific error type, you'll need to handle the error code.
Authentication errors
A special type of operation error is the AuthenticationError java, swift, objc, flutter, react native as it contains the SessionProvider accessible via sessionProvider().
Handling error codes
It is very important to be aware of the FIDO errors and handle them in an appropriate manner as FIDO-specific errors are not handled by a specific error subtype of OperationError.
The FIDO UAF error codes are also sent to the backend as part of the operation response where they are reported as client errors.
In this case, the backend will use the UAF Status Code 1498 Unacceptable Content as the response by the client will contain an empty assertion.
Together with the error code, the SDK sends a message describing the error. See Client error information sent to the backend.
We want to point out some of the errors explicitly as they will require specific handling by the mobile application.
There is currently a slight difference in how FIDO errors are handled between the platforms.
-
Android
All
OperationErrorobjects contain aFidoErrorCodejava, swift, objc, flutter, react native accessible viaerrorCode()describing the nature of the error. In case the error is a named error and not FIDO related, theFidoErrorCodevalue isUNKNOWN. -
iOS, Flutter and ReactNative
FIDO related operation errors are indicated by the
FidoErrorCodeswift, objc, flutter, react native property in the FIDO specific subtype of theOperationErrorswift, objc, flutter, react native. All other, non-FIDO related errors don't have theFidoErrorCodeproperty.The cross-platform plugins will not propagate the
FidoErrorCodeto the Dart or TypeScript side, when the error is a specific, "named"OperationError(for exampleOperationError.NetworkError).The difference to Android is that an error is either a "named" error or a
FidoErrorhaving aFidoErrorCodewhilst Android will always return aFidoErrorCodewith every error.For example, you can retrieve the
FidoErrorCodefromOperationFidoError.errorCodeswift, objc, flutter, react native andAuthenticationFidoError.errorCodeswift, objc, flutter, react native.
We intend to improve and align and simplify the error handling in this area with future SDK versions to ease app integration.
USER_LOCKOUT
This is the most prominent error, likely to occur with some frequency during the normal usage of the app and SDK.
The two scenarios leading to this error are:
- Too many failed fingerprint or face verification attempts leads to the mobile OS locking the biometric authenticator.
Although this lockout cannot be resolved programmatically, it's not permanent. To unlock the biometric authenticators, the user must provide the device passcode by for example locking or unlocking the phone. Additional information can be found in the locked biometric authenticators chapter.
- The user entered the PIN or password wrong too often and the brute force attack prevention locks the authenticator.
This is a permanent lockout, the Application PIN or Application Password authenticator affected must be deleted (either via deregistration or LocalData operation) and a new registration performed.
USER_CANCELED
The user canceling an operation leads to this FIDO UAF error being generated. However, this is to be considered a normal scenario where the user decides to deliberately decline an operation.
User cancellations are done by invoking the cancel() method in the CancelableHandler java, swift, objc, flutter, react native of the respective verification handles of the authenticator, account or authenticator selector.
When putting the app into the background, the operation is cancelled and the mobile SDK treats this as USER_CANCELED for biometric authenticators.
USER_NOT_RESPONSIVE
This is an inactivity timeout leading to the operation failing. The inactivity timeout can be configured during SDK initialisation with the userInteractionTimeoutInSeconds() java, swift, objc, flutter, react native method.
User interaction timeouts must be shorter than the operation timeout configured in the backend. A user interaction timeout value higher than the operation timeout value will lead to a failed operation indicated by the backend responding with UAF status code 1408 - Request timeout even if the user responded during the interaction timeout value. In this case, the SDK will still respond with USER_NOT_RESPONSIVE.
USER_NOT_ENROLLED
The operation failed because there is no authenticator registered to the user trying to perform the operation.
NO_SUITABLE_AUTHENTICATOR
No authenticator matching the authenticator policy specified by the backend is available to service the request, or the user declined to consent to the use of a suitable authenticator. As the backend specifies the allowed authenticators for an operation, it's necessary to be aware of the policies used. The following documentation provides additional policy-related information:
The following scenarios can generate the NO_SUITABLE_AUTHENTICATOR error:
- Registration operation
If the selected authenticator with the AuthenticatorSelectionHandler.aaid java, swift, objc, flutter, react native method is already registered for the user. Every “type” of authenticator (e.g. PIN or Fingerprint or Face) can only be registered once per user and device/app.
-
Authentication operation
- If the app tries to authenticate using credentials (an authenticator) that still exists in the backend, but has been removed only in the client.
- During authentication, the server sends a list of acceptable authenticator key identifiers as part of its policy, if the client has none of those keys (anymore) then no suitable authenticator can be used to answer the request.
- If the user/developer selects an authenticator that has not been registered yet. For example, if the user has a PIN authenticator registered, but the biometric authenticator is selected.
-
Registration and authentication operation
If the user (or developer) selects an authenticator that is not compliant with the policy of the server. For example if the server only allows to register/authenticate with biometrics and a PIN authenticator is selected during the operation. The
AuthenticatorSelectionContext.isPolicyCompliantjava, swift, objc, flutter, react native method returns whether a given authenticator is compliant with the server policy in use for the current operation (e.g. eligible for performing the current operation)
UNTRUSTED_FACET_ID
This error occurs typically when there is a misconfiguration of the server: the facets defined by the FIDO UAF server do not match the configuration of the application. The Facet ID chapter provides more information.
KEY_DISAPPEARED_PERMANENTLY
This error can occur in scenarios where the private key is no longer accessible by the authenticator, for example when a new biometric credential was defined in the OS settings, and during registration it was specified to invalidate the authenticator on new credentials.
Another scenario is when the user removed the device passcode and then recreated it. This invalidates all keys associated with the biometric and device passcode authenticators.
As this error is non-recoverable we recommend deleting the authenticator locally and in the backend; a new authentication registration is required.
PROTOCOL_ERROR
This error is very unlikely to occur, it indicates UAF protocol violation which points to an issue with the backend. Solving this issue will require analysing the backend to determine the root cause.
AUTHENTICATOR_ACCESS_DENIED
This is a rare error which could technically occur in scenarios where there is an issue accessing the key material and the cause is neither USER_LOCKOUT nor USER_CANCELED.
Consider this a "generic" low-level issue by Android and iOS related to keystore access.
We ourselves have not yet seen this error during our tests.
UNKNOWN
Indicates an error which is not FIDO UAF related, in this case you’ll get a one of the specific "named" errors returned by the SDK, such as:
- Multi-backend errors
- Out-of-band token errors
- Out-of-band payload errors
- Networking and backend errors
Unlikely to occur FIDO UAF errors
Some of the errors are very unlikely to occur in production but exist to adhere to the specification:
INSECURE_TRANSPORTindicating a non https connection.UNSUPPORTED_VERSIONimpossible to occur with the Nevis backend.INVALID_TRANSACTION_CONTENTimpossible to occur with the Nevis backend.INSUFFICIENT_AUTHENTICATOR_RESOURCESwould indicate the inability to create and store new key material in the secure hardware. We have never experienced this error so far.
Non-errors
Lastly, there are two "non-error" types:
NO_ERRORis set as the name indicates in case no UAF operation related error occurred.WAIT_USER_ACTIONis part of the normal lifecycle and is set when an authenticator is waiting for the user to provide his/her credentials.
Client error information sent to the backend
When a registration or an authentication fails on the device, the SDK informs the backend about the failure. The backend can then terminate the operation instead of waiting for it to time out. The SDK sends the FIDO UAF response without any assertion to the registration response service or the authentication response service. It adds the following attributes to the context of the request:
| Attribute | Description |
|---|---|
clientErrorCode | The numeric client error code. It corresponds to the FidoErrorCode the app receives in the onError() callback, for example 9 for KEY_DISAPPEARED_PERMANENTLY. |
clientErrorMessage | A human-readable text describing the error in more detail than the error code. The text generated by the SDK is in English, but it can contain texts of the operating system in the language of the device. It is meant for troubleshooting only. |
deviceId | The identifier of the device. Only sent for registration. |
This makes it possible to analyze problems occurring on end-user devices by looking at the nevisFIDO logs, without access to the device. The Analyzing Client Errors in the Backend Logs chapter describes how to do this.
Example client error context
The following context is sent when the user cancels the biometric prompt during an authentication on iOS:
{
"clientErrorCode": 3,
"clientErrorMessage": "Fido Error code: userCanceled. Details: User has canceled the operation. (Authenticator: F1D0#1002)"
}
The following context is sent when a registration fails on Android because the biometric key was invalidated:
{
"clientErrorCode": 9,
"clientErrorMessage": "FIDO Error code: KEY_DISAPPEARED_PERMANENTLY. Details: Error invoking getSignatureInstance with authenticator F1D0#0003. Details: Cryptography error. errorCode: 00001015. errorMsg: Unable to get signature instance. Cause: android.security.keystore.UserNotAuthenticatedException: User not authenticated",
"deviceId": "..."
}
Availability of the client error message
| Platform | clientErrorCode | clientErrorMessage |
|---|---|---|
| Android | All supported versions | Since 4.3.1. More details are included since 4.4.0 and 4.6.0. |
| iOS | All supported versions | Since 4.4.0 |
| Flutter and React Native | All supported versions | Provided by the underlying native SDK. Available on Android when the plugin uses Android SDK 4.3.1 or later, and on iOS when it uses iOS SDK 4.4.0 or later. |
nevisFIDO logs the clientErrorMessage since the versions 9.2605.0 (Rolling Release) and 8.2607.0 (LTS26). Older nevisFIDO versions ignore the attribute and only log Unknown property "clientErrorMessage" in JSON object of expected type .... The operation itself is not affected.
When is the client error information sent
The client error information is sent when the operation fails after the SDK received the FIDO UAF request from the backend and before it sent a successful FIDO UAF response. This covers in-band and out-of-band registrations and authentications, for example:
- the facet ID of the app is not trusted by the backend (
UNTRUSTED_FACET_ID), - the trusted facet list could not be retrieved (
UNTRUSTED_FACET_ID). Since iOS SDK 4.6.0, the app receives aNetworkErrorwith a cause of typeuntrustedFacetIDfor a network failure while fetching the list, instead of a FIDO UAF error. The SDK still sendsUNTRUSTED_FACET_IDto the backend, so the error is visible in the nevisFIDO log, - no registered or no policy compliant authenticator is available (
NO_SUITABLE_AUTHENTICATOR), - the user cancels the account or authenticator selection, or the user verification (
USER_CANCELED), - the user does not respond in time (
USER_NOT_RESPONSIVE), - the authenticator is locked (
USER_LOCKOUT), - the key was invalidated, for example because the biometric enrollment changed (
KEY_DISAPPEARED_PERMANENTLY), - errors from the operating system biometric API, the Android Keystore or the iOS Keychain (
AUTHENTICATOR_ACCESS_DENIEDorUNKNOWN).
No client error information is sent in the following cases. Either there is no pending FIDO UAF operation the error could be associated with, or the backend already knows the result:
- errors that occur before the FIDO UAF request was received, for example network errors while starting the operation,
- errors that occur after the FIDO UAF response was sent, for example the backend rejecting the response or network errors,
- deregistration, PIN or password change, and device information change operations,
- on iOS, errors that are not FIDO UAF errors, for example a multi-backend error.
Content of the client error message
The message is built from the error chain inside the SDK and can include:
- the name of the FIDO UAF error code,
- the Authenticator Attestation ID (AAID) of the authenticator involved, for example
F1D0#0003, - the error returned by the operating system, for example the
BiometricPrompterror code and message on Android or theLAErrordescription on iOS. Texts provided by the operating system can be in the language of the device, - the failing internal processing step, for example
ASM operation=REGISTER; phase=store_registrationon Android, - the type and message of the underlying exception on Android, for example
android.security.keystore.KeyPermanentlyInvalidatedException, - on Android, the username of the account and the backend URL, when the error is related to them, for example when an authenticator is already registered for the user.
The message has no defined format. It differs between Android and iOS and between SDK versions.
The content of clientErrorMessage is not part of the public API. It is free text. It is not localized for end users, and its content can change with any SDK version. Use it for troubleshooting only: do not parse it to drive business logic in the backend, and rely on clientErrorCode for automated processing.
The message is designed to not contain secrets such as PINs, passwords or key material. It can contain usernames, AAIDs, URLs, and texts from the operating system. Consider this when defining the retention and the access to the nevisFIDO logs.
Account and authenticator selection
If the app cancels the account or authenticator selection by invoking cancel() on the AccountSelectionHandler or the AuthenticatorSelectionHandler, the backend receives the code USER_CANCELED with a generic message. The app cannot provide its own message.
For out-of-band authentications started without an AccountSelector, the default account selection of the Android SDK reports a more specific code and message. For example, when no account has a policy compliant authenticator, the backend receives NO_SUITABLE_AUTHENTICATOR with the message No authenticator found that is compliant with the policy..
Multi-backend errors
Two errors of note regard the SDKs multi-backend feature and usually indicate a user interaction error where the end user "accidentally" used the wrong backend:
UserAlreadyRegisteredInAnotherServeroccurs during a registration operation when the exact same username is already registered in the client and the current operation tries to register it again but with a different backend.UserNotRegisteredInServercan only occur with usernameless authentication where the end user selected an account which is not registered in the backend which started the operation.
Out-of-band token errors
Two errors of note are specific to out of band operations:
TokenAlreadyRedeemedindicates a "double redemption" of an out-of-band token. A token can only be used once to prevent reply attacks.TokenExpiredA redeem token has a limited lifetime controlled via the nevisFIDO instance configuration.
Both errors require a new operation to be started by dispatching a new token form the backend-side.
Out-of-band payload errors
The Nevis SDK provides methods to decode out-of-band payloads.
As the payloads are encrypted, a DecryptionError java, swift, objc, flutter, react native can occur in two scenarios:
- The key used to decrypt the out-of-band payload does not exist anymore.
- The user is trying to redeem a token which was generated for another mobile device.
In addition, a MalformedPayload java, swift, objc, flutter, react native error may be thrown if the SDK was unable to parse the JSON payload.
Networking and backend related errors
NetworkErroris indicating connectivity issues. Anything leading to the backend not being reachable, or the backend returning an unexpected HTTP error, will lead to this error.ClockSkewTooBigis a quite specific error which during "normal operations" should never occur but nevertheless can during device information change, check and synchronize device information or fetching pending operations. The issue causing this error is a "too large" discrepancy between the server's and the mobile client's system clock and can be addressed by the user updating it.OperationNotSupportedByBackendcan occur with the Nevis Identity Suite backend in case the nevisFIDO component version is too old and not supporting the operation.
NetworkError and TLS certificate validationThe NetworkError is also used in case the SDK cannot validate the backends TLS certificate chain and Root CA. The SDK uses the operating systems trust store to validate the backends TLS certificate (specifically the certificate chain leading to a valid root CA). Older operating system versions may not contain newer Root CA certificates anymore thus leading to the TLS validation failing as the certificate chain is untrusted.
This can affect the following operating systems (as of July 2025):
- iOS 17 or lower.
- Android 13 or lower.
- Android 14 or higher depend on receiving OTA (over the air) updates to update the systems trust store.
End users should try to update their operating system and/or security patches to the latest available version. There is no workaround as validating the TLS connection is one of the core security features.
As described in the NetworkError part, issues directly related to connectivity (e.g. no internet connection at all) are not that easily distinguishable for error occurring when the backend was reachable.
We plan to improve this in future SDK versions.