feat: Improve Error Handling #762

lewie9021 · 2025-06-28T07:14:06Z

This PR introduces standardised error handling across both iOS and Android. In particular, I've tried to solve the following problems:

Localisation Issues: Android error messages are localised making it either difficult, or in some cases, impossible to reliably detect specific scenarios through message parsing.
Platform Inconsistency: Error handling differs significantly between iOS and Android, requiring platform-specific logic.
Root Cause Masking: Many errors are overwritten with custom messages like "Could not decrypt data with alias: $alias", making debugging difficult and hiding the actual cause of failures.

My approach to error codes attempts to balance cross-platform consistency for common scenarios (like user cancellation) with platform-specific codes where additional control is needed. The mappings represent my best understanding of the various failure scenarios. I'm more than happy to get feedback on whether we need additional, fewer, or different error codes to better serve the community's needs.

I've made some other notable changes in this PR that I'd like to call out, specifically:

Renamed CryptoFailedException → KeychainException
- Added error code support
- Added overloads to simplify error creation with codes
- Removed the need for reThrowOnError and "Wrapped error:" prefixes
Refactored iOS Error Mapping
- Combined codeForError and messageForError to help with maintainability.
- Added mapping of LocalAuthentication error codes. I realise these errors will only throw when setting right now. If we ever use LAContext.canEvaluatePolicy when getting keys in the future, we can instantly provide more granularity around scenarios such as not enrolled (i.e. user disables biometrics for the app) or not available (i.e. perhaps they've denied permission).
Existing Error Codes
- Removed E_SUPPORTED_BIOMETRY_ERROR: This error code felt unnecessary as the assumption is callees wouldn't get much value out of the two distinct errors.
- Renamed E_EMPTY_PARAMETERS → E_INVALID_PARAMETERS: Clearer intent.
- Renamed E_KEYSTORE_ACCESS_ERROR → E_STORAGE_ACCESS_ERROR: Platform-agnostic given KeyStore suggests Android-only.
- Renamed E_UNKNOWN_ERROR → E_INTERNAL_ERROR: Unknown error suggests they're errors we're not aware of but they include custom errors directly thrown in the code. I initially had both but from a consumer perspective, they mean the same thing - something went wrong and we should probably display a generic message to a user.

Usage

import * as Keychain from 'react-native-keychain';

try {
  await Keychain.getGenericPassword();
} catch (error) {
  switch (error.code) {
    case Keychain.ERROR_CODE.AUTH_CANCELED:
      console.log('Authentication was canceled');
      break;
    case Keychain.ERROR_CODE.BIOMETRIC_TIMEOUT:
      console.log('Biometric prompt timed out');
      break;
    case Keychain.ERROR_CODE.BIOMETRIC_LOCKOUT:
      console.log('Too many failed attempts, biometric authentication locked');
      break;
    default:
      console.log(`Keychain error: ${error.code} - ${error.message}`);
  }
}

- Added additional overloads to simplify usage. - Removed need for reThrowOnError (and "Wrapped error: " prefix).

…renamed from E_BIOMETRIC_ERROR).

Copilot

Pull Request Overview

This PR standardizes error handling across iOS and Android by introducing language‐independent error codes, consolidating error mapping logic, and replacing the previous CryptoFailedException with a unified KeychainException.

Added ERROR_CODE enum and exposed it in the public API.
Implemented platform‐specific error mappings on iOS and Android to return structured { code, message }.
Replaced CryptoFailedException with KeychainException throughout Android, updating promise rejects and handlers.

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/index.ts	Exported new `ERROR_CODE` in public API
src/enums.ts	Added `ERROR_CODE` enum with standardized codes
ios/RNKeychainManager/RNKeychainManager.m	Mapped LA and Sec errors to codes and unified reject logic
android/src/main/java/com/oblador/keychain/resultHandler/ResultHandlerNonInteractive.kt	Switched to `KeychainException`, removed `CryptoFailedException`
android/src/main/java/com/oblador/keychain/resultHandler/ResultHandlerInteractiveBiometric.kt	Added BiometricPrompt error‐to‐code mapping
android/src/main/java/com/oblador/keychain/exceptions/KeychainException.kt	Introduced `KeychainException` with errorCode support
android/src/main/java/com/oblador/keychain/exceptions/CryptoFailedException.kt	Removed legacy `CryptoFailedException`
android/src/main/java/com/oblador/keychain/cipherStorage/CipherStorageKeystoreRsaEcb.kt	Updated to throw `KeychainException`
android/src/main/java/com/oblador/keychain/cipherStorage/CipherStorageKeystoreAesGcm.kt	Updated to throw `KeychainException`
android/src/main/java/com/oblador/keychain/cipherStorage/CipherStorageKeystoreAesCbc.kt	Updated to throw `KeychainException`
android/src/main/java/com/oblador/keychain/cipherStorage/CipherStorageBase.kt	Updated exception types and error codes
android/src/main/java/com/oblador/keychain/cipherStorage/CipherStorage.kt	Updated throws annotations to use `KeychainException`
android/src/main/java/com/oblador/keychain/KeychainModule.kt	Refactored promise rejects and removed old error codes

Comments suppressed due to low confidence (1)

android/src/main/java/com/oblador/keychain/resultHandler/ResultHandlerNonInteractive.kt:14

[nitpick] When throwing KeychainException for interactive mode requirement, consider specifying an explicit errorCode such as Errors.E_AUTH_INTERACTION_NOT_ALLOWED instead of relying on the default E_INTERNAL_ERROR, to improve error handling clarity.

    val failure = KeychainException("Interactive mode required but unavailable.")

Copilot · 2025-07-07T20:11:04Z

ios/RNKeychainManager/RNKeychainManager.m

+    [[LAContext new] canEvaluatePolicy:LAPolicyDeviceOwnerAuthentication error:&aerr];
+    if (aerr) {
      return rejectWithError(reject, aerr);


The code calls canEvaluatePolicy but ignores its boolean return value. It should capture the return (e.g., BOOL canAuthenticate = ...) and handle the case where canAuthenticate is NO even if error is nil.

Suggested change

[[LAContext new] canEvaluatePolicy:LAPolicyDeviceOwnerAuthentication error:&aerr];

if (aerr) {

return rejectWithError(reject, aerr);

LAContext *context = [LAContext new];

BOOL canAuthenticate = [context canEvaluatePolicy:LAPolicyDeviceOwnerAuthentication error:&aerr];

if (!canAuthenticate) {

NSError *authError = aerr ?: [NSError errorWithDomain:@"RNKeychainManager" code:-1 userInfo:@{NSLocalizedDescriptionKey: @"Authentication policy cannot be evaluated."}];

return rejectWithError(reject, authError);

This change was to fix a scenario where we were potentially rejecting with a nil error when canAuthenticate was false.

Perhaps I should throw a custom error message when canAuthenticate is false to maintain the fix and prevent the regression 🤔

Copilot · 2025-07-07T20:11:05Z

android/src/main/java/com/oblador/keychain/cipherStorage/CipherStorageKeystoreRsaEcb.kt

-                    throw CryptoFailedException("Unknown error: ${e.message}", e)
-                }
-            }
+            throw KeychainException(e.message, e)


[nitpick] Throwing a generic KeychainException with only the original exception message loses context such as the alias. Consider including a descriptive message (e.g., "Could not encrypt data for service $alias") to aid debugging.

Suggested change

throw KeychainException(e.message, e)

throw KeychainException("Could not encrypt data for service $safeAlias: ${e.message}", e)

This is perhaps an oversight I've made in other areas too. I'll look to fix this soon 🙂

DorianMazur · 2025-07-07T20:12:09Z

android/src/main/java/com/oblador/keychain/KeychainModule.kt

          Log.e(KEYCHAIN_MODULE, e.message, e)
-          promise.reject(Errors.E_EMPTY_PARAMETERS, e)
-        } catch (e: CryptoFailedException) {
+          promise.reject(Errors.E_INVALID_PARAMETERS, e)


Why it's E_INVALID_PARAMETERS now if we are throwing this error when parameters are empty?

This was to consolidate various cases where an exception is thrown due to invalid parameters, including cases where we get the empty parameters exception.

It's an error code that essentially signals to the developer that they've not configured the library correctly and perhaps need to use methods that help determine what's available on the users device

lewie9021 · 2025-07-20T16:08:03Z

android/src/main/java/com/oblador/keychain/cipherStorage/CipherStorageKeystoreRsaEcb.kt

            val result = innerEncryptedCredentials(safeAlias, password, username)
            handler.onEncrypt(result, null)
-        } catch (e: Exception) {
+        } catch (fail: Throwable) {


Switched to Throwable for consistency with AES Cipher implementation

lewie9021 · 2025-07-20T18:17:40Z

Hey @DorianMazur 🙂 I believe I've addressed the issues raised now if you'd like to take a look 👍

I noticed an issue on Android while testing for the E_AUTH_INVALIDATED error code (aka KeyPermanentlyInvalidatedException). It seems there's a problem with how keys are generated if I understand correctly? It seems the infamous validity duration is partly to blame too. I believe we should be setting the value to -1 for setUserAuthenticationValidityDurationSeconds or 0 for setUserAuthenticationParameters according to the Android documentation. Arguably, this is a separate issue to this PR but thought I'd call it out should there be an assumption that this has been fixed

lewie9021 · 2025-07-31T18:20:30Z

Hey @DorianMazur! 🙂

Have you had chance to take a look at my changes since the initial review? I'm interested to know if there's anything else you'd like me to do on this and what it would take to make it into an upcoming release!

DorianMazur · 2025-08-27T17:12:42Z

Hey @lewie9021
Amazing work, sorry for the delay!

lewie9021 added 26 commits June 28, 2025 06:42

Added error code constants for both platforms.

8278bc9

Enhanced exception to support error codes

c0d8573

- Added additional overloads to simplify usage. - Removed need for reThrowOnError (and "Wrapped error: " prefix).

Removed instances of overwriting the real error.

5357baa

Applied correct error codes.

ed63e6c

Added mapping of various BiometricPrompt error codes.

9828afe

Added some consistency with Android when an unknown error occurs.

4b11f94

Removed E_SUPPORTED_BIOMETRY_ERROR error code.

7902701

Renamed CryptoFailedException to KeychainException.

4fe4764

Made default error code E_UNKNOWN_ERROR.

0417390

Removed CRYPTO_FAILED error code.

6915084

Removed INTERNAL_ERROR error code.

2154c8c

Improved error code mapping.

4d9af53

Removed need for E_KEYCHAIN_DUPLICATE_ITEM.

e2aa99d

Removed E_INTERACTIVE_MODE_UNAVAILABLE error.

2983292

Removed KEYCHAIN_INTERACTION_NOT_ALLOWED to IOS_INTERACTION_NOT_ALLOWED.

c000257

Split up some biometric error codes.

1599812

Consolidated error info.

9e750ed

Removed unnecessary cases.

1cfc161

Fixed case where rejectWithError could be called with no error.

ec71b53

Fixed use of wrong error.

1a1945a

Simplified logic.

c7a6122

Added support for mapping LocalAuthentication errors.

e7c6e44

Omit extra iOS cancel code until further investigation.

4650dde

Moved to generic canceled error code.

e79b501

Improved function name.

dd4f579

Avoid defaulting to unknown errors.

61bbaa2

lewie9021 force-pushed the master branch from 7f87813 to 61bbaa2 Compare June 30, 2025 06:23

lewie9021 added 3 commits June 30, 2025 07:40

Correct error code and formatting.

0413da0

Fixed mapping of unhandled LA error codes.

cfc83b0

Consolidated E_AUTH_UNKNOWN_ERROR & E_AUTH_FAILED into E_AUTH_ERROR (…

0da3862

…renamed from E_BIOMETRIC_ERROR).

lewie9021 added 6 commits July 6, 2025 08:07

Renamed enum to ERROR_CODE.

0bcba5e

Removed reformatting of unknown errors.

abda4a5

Consolidated configuration errors.

c0fb25e

Renamed KEY_PERMANENTLY_INVALIDATED to AUTH_INVALIDATED.

2ade93c

Minor refactor.

b42bbab

Consolidated E_UNKNOWN_ERROR into E_INTERNAL_ERROR.

11ae0fb

DorianMazur requested a review from Copilot July 7, 2025 20:09

Copilot AI reviewed Jul 7, 2025

View reviewed changes

DorianMazur reviewed Jul 7, 2025

View reviewed changes

Repository owner deleted a comment from Copilot AI Jul 7, 2025

lewie9021 changed the title ~~Improve Reliability of Error Handling~~ Improve Error Handling Jul 11, 2025

lewie9021 added 2 commits July 20, 2025 16:34

Fixed logic when can't authenticate.

ccdf7e7

Wrapped error messages.

f584aec

lewie9021 commented Jul 20, 2025

View reviewed changes

lewie9021 requested a review from DorianMazur July 20, 2025 17:08

This was referenced Jul 20, 2025

[suggestion] Document and/or improve OS keystore exceptions #747

Closed

Inconsistent Error Messages Between iOS and Android for Cancelled Biometry Operations #609

Closed

lewie9021 deleted the branch oblador:master July 26, 2025 16:20

lewie9021 closed this Jul 26, 2025

lewie9021 deleted the master branch July 26, 2025 16:20

lewie9021 restored the master branch July 26, 2025 16:21

lewie9021 reopened this Jul 26, 2025

lewie9021 added 2 commits July 28, 2025 17:51

Added documentation alongside error codes.

8d65028

Fixed build error.

926ab66

DorianMazur merged commit d4dc54e into oblador:master Aug 27, 2025

lewie9021 changed the title ~~Improve Error Handling~~ feat: Improve Error Handling Sep 6, 2025

lewie9021 mentioned this pull request Sep 6, 2025

feat: Add KeychainError #769

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: Improve Error Handling #762

feat: Improve Error Handling #762

Uh oh!

lewie9021 commented Jun 28, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jul 7, 2025

Uh oh!

lewie9021 Jul 8, 2025 •

edited

Loading

Uh oh!

Copilot AI Jul 7, 2025

Uh oh!

lewie9021 Jul 8, 2025

Uh oh!

DorianMazur Jul 7, 2025

Uh oh!

lewie9021 Jul 8, 2025

Uh oh!

lewie9021 Jul 20, 2025

Uh oh!

lewie9021 commented Jul 20, 2025

Uh oh!

lewie9021 commented Jul 31, 2025

Uh oh!

DorianMazur commented Aug 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-    [[LAContext new] canEvaluatePolicy:LAPolicyDeviceOwnerAuthentication error:&aerr];
-    if (aerr) {
-      return rejectWithError(reject, aerr);
+    LAContext *context = [LAContext new];
+    BOOL canAuthenticate = [context canEvaluatePolicy:LAPolicyDeviceOwnerAuthentication error:&aerr];
+    if (!canAuthenticate) {
+      NSError *authError = aerr ?: [NSError errorWithDomain:@"RNKeychainManager" code:-1 userInfo:@{NSLocalizedDescriptionKey: @"Authentication policy cannot be evaluated."}];
+      return rejectWithError(reject, authError);

	throw KeychainException(e.message, e)
	throw KeychainException("Could not encrypt data for service $safeAlias: ${e.message}", e)

Uh oh!

feat: Improve Error Handling #762

feat: Improve Error Handling #762

Uh oh!

Conversation

lewie9021 commented Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Usage

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

lewie9021 Jul 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

lewie9021 Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

DorianMazur Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

lewie9021 Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

lewie9021 Jul 20, 2025

Choose a reason for hiding this comment

Uh oh!

lewie9021 commented Jul 20, 2025

Uh oh!

lewie9021 commented Jul 31, 2025

Uh oh!

DorianMazur commented Aug 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lewie9021 commented Jun 28, 2025 •

edited

Loading

lewie9021 Jul 8, 2025 •

edited

Loading