Skip to main content
The React Native SDK wraps native passkey errors from iOS and Android into ParaPasskeyError, a structured error class with a typed error code, platform detection, an actionable suggestion, and a link back to this page. Every passkey operation (registerPasskey, loginWithPasskey) throws a ParaPasskeyError on failure. 
import { ParaPasskeyError } from "@getpara/react-native-sdk";

try {
  await para.registerPasskey(authState);
} catch (error) {
  if (error instanceof ParaPasskeyError) {
    console.log(error.code);       // "RP_ID_MISMATCH"
    console.log(error.platform);   // "android"
    console.log(error.suggestion); // actionable fix
  }
}
Each error includes these properties:
PropertyTypeDescription
codeParaPasskeyErrorCodeMachine-readable error code from the table below
platform'ios' | 'android' | 'unknown'Platform that produced the error
messagestringOriginal error message from the native layer
suggestionstringActionable guidance for resolving the error
docsUrlstringDirect link to the relevant section on this page
causeunknownOriginal error object for deep debugging

​
USER_CANCELLED

The user dismissed the passkey prompt (tapped cancel, swiped away, or declined biometric authentication). Platforms: iOS, Android What to do: This is expected behavior. Handle it gracefully by catching the error and allowing the user to retry. Do not treat this as a fatal error or show an error screen.

​
TIMED_OUT

The passkey operation exceeded the system timeout before the user completed the biometric prompt. Platforms: iOS, Android What to do: Prompt the user to try again. If this happens frequently, check whether the timeout configuration in your passkey request is too short for your users’ environment.

​
BAD_CONFIGURATION

The app’s entitlements, associated domains, or passkey request parameters are misconfigured. Platforms: iOS, Android What to do:
  • iOS: Verify that your Xcode project (or app.json for Expo) includes the associated domains entitlement with webcredentials:app.beta.usecapsule.com and webcredentials:app.usecapsule.com. Confirm your Team ID and Bundle ID are registered in the .
  • Android: Verify your SHA-256 signing certificate fingerprint is registered in the under your API key’s Native Passkey Configuration.
This code also covers InvalidChallenge and InvalidUser errors from the native layer, which indicate malformed request parameters. These are typically SDK internal issues — if you encounter them, please .

​
NOT_CONFIGURED

The credential provider is not set up on the device. Platforms: Android What to do: This is Android-specific. Ensure Google Play Services is available and that a Google account is signed in on the device. Devices without Google Play Services (some Huawei devices, custom ROMs) cannot use passkeys through the Credential Manager API.

​
RP_ID_MISMATCH

The app’s signing certificate does not match what is registered for the relying party domain. Platforms: Android What to do: This is the most common Android passkey error. Debug and release builds use different signing keys, and the SHA-256 fingerprint registered in the Developer Portal must match the build you are testing. Get your debug fingerprint: 
keytool -list -v -keystore ~/.android/debug.keystore \
  -alias androiddebugkey -storepass android -keypass android
Get your release fingerprint: 
keytool -list -v -keystore <your_keystore_path>
Register both fingerprints in the to avoid this error across build types.
After registering a new fingerprint, Google can take up to 24 hours to verify it. Check the verification status in the Developer Portal under your API key’s Native Passkey Configuration.

​
NOT_SUPPORTED

Passkeys are not supported on this device. Platforms: iOS, Android What to do: Passkeys require iOS 16+ or Android API 28+. If the device does not meet these requirements, fall back to an alternative authentication method (email OTP, password, or social login). Use this error code to detect unsupported devices and present the appropriate fallback UI.

​
NO_CREDENTIALS

No passkeys are stored on this device for the requested user. Platforms: Android (login only) What to do: This means the user has not registered a passkey on this device, or is on a different device than where the passkey was created. Ensure your auth flow calls registerPasskey() for new users before attempting loginWithPasskey(). If the user previously registered on another device, they will need to register again on this one or use cross-device passkey authentication if supported.

​
REQUEST_FAILED

The passkey request failed at the system level. Platforms: iOS, Android What to do:
  • iOS: Check that your associated domains entitlement is configured correctly and that your Team ID and Bundle ID are registered in the . Also verify the device can reach Apple’s CDN to validate the Apple App Site Association file.
  • Android: Verify your SHA-256 fingerprint is registered correctly. See the RP_ID_MISMATCH section for fingerprint instructions.

​
INTERRUPTED

The passkey operation was interrupted by the system before it could complete. Platforms: iOS, Android What to do: This can happen when the app is backgrounded during a passkey operation, or when another authentication prompt takes priority. The operation can be safely retried.

​
UNKNOWN

An unrecognized error occurred during the passkey operation. Platforms: iOS, Android What to do: Check the cause property on the error object for the original native error details. If the error persists, with the full error output from the development console. In development builds, the SDK automatically logs a diagnostic block with the error code, platform, relying party ID, and suggestion.

​
Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:
  1. 1

    A detailed description of the problem you’re encountering.

  2. 2

    Any relevant error messages or logs.

  3. 3

    Steps to reproduce the issue.

  4. 4

    Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.