Analyzing Client Errors in the Backend Logs
When a registration or an authentication fails on a mobile device, the mobile SDK reports the failure to nevisFIDO together with a client error code and a client error message. nevisFIDO writes this information to its log. The nevisFIDO log is therefore often the quickest way to find out why an operation failed for an end user. You do not need access to the device or the app logs.
This chapter describes where the client error information can be found, how to find the relevant log entries, and how to interpret the most frequent errors.
Where the client error information is available
| Location | clientErrorCode | clientErrorMessage |
|---|---|---|
nevisFIDO log (nevisfido.log), default configuration | ✅ | ✅ (nevisFIDO 9.2605.0 RR, 8.2607.0 LTS26, and later) |
nevisFIDO request log (CommonsRequestLoggingFilter on DEBUG) | ✅ (raw request) | ✅ (raw request) |
| Status Service response | ✅ | ❌ |
| nevisAuth, for example the FidoUafAuthState | ✅ (through the Status Service) | ❌ |
App, onError() callback | ✅ (FidoErrorCode) | ✅ (see below) |
The clientErrorMessage is not stored by nevisFIDO. The log is the only place where it is available on the backend side.
The app receives the same information in the error object passed to the onError() callback, not as a separate attribute. On Android, the message of the returned error contains the client error message. On iOS, the FidoError contains the error code and the underlying error as cause, from which the SDK builds the client error message. If the app logs or reports these errors, they can be correlated with the nevisFIDO log entries.
Log configuration
No additional configuration is required. The client error information is logged on level INFO by the loggers below, which are covered by the default category ch.nevis.auth.fido on level INFO in the nevisFIDO logging configuration:
ch.nevis.auth.fido.core.businesslogic.uaf.fidouaf.impl.RegistrationResponseServiceImplch.nevis.auth.fido.core.businesslogic.uaf.fidouaf.impl.AuthenticationResponseServiceImpl
Make sure that ch.nevis.auth.fido is not set to a level higher than INFO, for example WARN.
Optionally, set org.springframework.web.filter.CommonsRequestLoggingFilter to DEBUG to log every incoming request including the headers and the payload. This shows the SDK and operating system version of the client in the User-Agent header. It produces a large volume of log entries and logs personal data such as IP addresses, so enable it only temporarily.
Log entries of a failed operation
When nevisFIDO receives a FIDO UAF response with a client error, it logs the following entries:
This status code is generated when there is an error at the client, and no assertions are generated: KEY_DISAPPEARED_PERMANENTLY
Client error message: FIDO Error code: KEY_DISAPPEARED_PERMANENTLY. Details: Error creating authentication assertion with authenticator F1D0#0003. Details: Cryptography error. ...
Authentication Response did not contain valid Assertion (validation of all 0 Assertions failed).
- The first entry contains the name of the client error code.
- The second entry contains the client error message sent by the SDK. It is only logged if the SDK sent a message, see Availability of the client error message.
- The third entry describes why nevisFIDO rejects the response. As the SDK does not send any assertion in case of a client error, this is typically
Authentication Response did not contain valid AssertionorRegistration Response did not contain valid Assertion.
The outcome depends on the state of the operation in nevisFIDO when the response arrives:
| State of the operation | UAF status code |
|---|---|
| Active, the response contains no assertion because of the client error | 1498 (Unacceptable Content). The Status Service reports the operation as failed. |
| Canceled through the Cancel Service beforehand | 1404 (Not Found). The Status Service keeps reporting the operation as cancelled. |
| Already timed out in the backend | 1408 (Request Timeout) |
Only the first case is a failure caused by the client. In the other cases, the operation was already terminated on the server side before the client error arrived. The client error then only explains what happened on the device in the meantime, for example USER_NOT_RESPONSIVE when the user interaction timeout is longer than the operation timeout of the backend.
The prefix of each line depends on the configured log pattern. The default pattern of a nevisFIDO instance contains the timestamp, the thread, the conversation ID, and the logger name. The logger name is shortened to its last 20 characters, which is nResponseServiceImpl for both the registration and the authentication response service. Kubernetes deployments use a different pattern which contains the trace ID and the span ID, see the examples in Component logging configuration options.
nullnevisFIDO can also log the first entry with the value null. This happens when a successful authentication response does not contain a client error code at all, which is the case for authentications with the Android SDK. Such entries do not indicate an error and can be ignored.
Finding client errors
The following examples assume that the nevisFIDO log files are available locally. For Kubernetes deployments, see Log access and streaming on how to access the logs.
List all client error messages:
grep -h "Client error message:" nevisfido.log*
Count the client errors by error code, to see which errors are the most frequent:
grep -ho "no assertions are generated: [A-Z_]*" nevisfido.log* | sort | uniq -c | sort -rn
Group the client error messages, ignoring the authenticator identifiers, to find recurring problems:
grep -ho "Client error message: .*" nevisfido.log* | sed -E 's/F1D0#[0-9]+/F1D0#xxxx/g' | sort | uniq -c | sort -rn | head -20
Correlating a client error with a user or a device
The client error entries do not consistently contain the username. On Android, the client error message can contain the username when the error is related to the account, for example when an authenticator is already registered for the user. If the message does not identify the user, correlate the error with a specific user or device as follows:
- Use the timestamp of the failed operation reported by the user or the app to find the client error entries in the nevisFIDO log. Within nevisFIDO, the thread name or the conversation ID of these entries identifies the other entries of the same request.
- To find the related entries in the logs of nevisProxy and nevisAuth, use the trace ID. nevisProxy propagates it to the other Nevis components, see the
trIDfield in Component logging configuration options. Thread names are local to a process and are reused for unrelated requests, so they cannot be used to correlate entries across components. - With
CommonsRequestLoggingFilteronDEBUG, the raw request of the failed operation contains thecontextwithclientErrorCodeandclientErrorMessage, theX-Request-IDheader and theUser-Agentheader. TheUser-Agentheader has the formNMASDK/<SDK version> (<device model>; <operating system and version>) <app identifier>/<app version>and makes it possible to determine whether an error only occurs with a specific SDK version, operating system version, or device model. - For registrations, the
contextalso contains thedeviceId, which shows whether repeated failures originate from the same device.
Interpreting frequent client errors
The table below lists the client errors most frequently seen in production, together with the typical message content. The exact messages differ between Android and iOS and between SDK versions. See Handling error codes for a description of each error code.
| Client error code | Typical message content | Likely cause | Recommended action |
|---|---|---|---|
USER_CANCELED (3) | The user declined any necessary part of the interaction, User has canceled the operation | The user canceled the operation, or the app was put into the background during a biometric verification. | No action needed, unless the error occurs frequently, which can point to a usability issue in the app. |
USER_NOT_RESPONSIVE (14) | timed-out, The user took too long | The user did not respond within the user interaction timeout. | Check the user interaction timeout of the app. |
NO_SUITABLE_AUTHENTICATOR (5) | already registered for user, not compliant with the policy, No authenticator is registered for the user, multiple accounts defined | The selected authenticator is already registered or not allowed by the policy, the authenticator was removed on the device, or an out-of-band authentication without username was started on a device with several accounts and without AccountSelector. | Check the policy and the account and authenticator selection of the app. |
UNTRUSTED_FACET_ID (7) | No matching facet found for appFacetId, not found in the trusted facet list, Failed to fetch the trusted facet list | The facet ID of the app is not configured in nevisFIDO, or the facet list could not be downloaded, for example because of an HTTP error. | Compare the facet ID in the message with the nevisFIDO facet configuration. For download failures, check the HTTP status and the URL in the message. |
KEY_DISAPPEARED_PERMANENTLY (9) | KeyPermanentlyInvalidatedException, UserNotAuthenticatedException, cannot be restored | The key of the authenticator was invalidated, for example because the biometric enrollment or the device passcode changed. | The user must register again. See KEY_DISAPPEARED_PERMANENTLY. |
USER_LOCKOUT (16) | is locked out, is permanently locked out | Too many failed biometric attempts (temporary) or too many wrong PIN or password attempts (permanent). | See USER_LOCKOUT. |
AUTHENTICATOR_ACCESS_DENIED (12) | Authentication error using biometrics API. Error code <n>, Access to this operation is denied. Cause: | The operating system rejected the access to the key or the biometric verification. The message contains the error of the operating system. | Look up the error code of the operating system, for example in the Android BiometricPrompt documentation. Check whether the error is limited to specific device models or operating system versions. |
UNKNOWN (255) | StrongBox, Keychain, Cryptography error, ASM operation= | An unexpected error in the secure hardware, the keystore or the SDK, often specific to some device models. | Collect the messages, the device models and the operating system versions, and contact Nevis support. |
UNKNOWN (255), Android only | Unable to get signature instance, UserNotAuthenticatedException: User not authenticated | The biometric verification succeeded, but the Android Keystore still refuses access to the key. Some failures are device-specific. Android SDK 4.3.1 fixed failures after insecure device unlock, including camera-based face recognition. | Check the SDK version and upgrade versions earlier than 4.3.1 for the insecure-unlock issue. If failures persist, check for device-specific patterns and operating system updates, or use another authenticator, such as the PIN or password authenticator. |
UNKNOWN (255), iOS only | because the device is locked, because protected data is unavailable | The device was locked during the operation, so the iOS Keychain was not accessible. This is a temporary condition. Since iOS SDK 4.6.1, the SDK reports it with this message instead of a generic keychain error. A dedicated error code may be introduced in a later version. | No action needed, unless the error occurs frequently. The user can retry the operation after unlocking the device. |
When contacting Nevis support about client errors, provide the complete client error messages, the SDK version, the device models and the operating system versions, and the approximate number of affected users.