> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native and Expo Troubleshooting

> Resolving integration issues for Para in React Native and Expo environments

export const Link = ({href, label, newTab = false}) => {
  const [isHovered, setIsHovered] = useState(false);
  return <a href={href} target={newTab ? '_blank' : '_self'} rel={newTab ? 'noopener noreferrer' : undefined} className="not-prose inline-block relative text-black font-semibold cursor-pointer border-b-0 no-underline" onMouseEnter={() => setIsHovered(true)} onMouseLeave={() => setIsHovered(false)}>
      {label}
      <span className={`absolute left-0 bottom-0 w-full rounded-sm bg-gradient-to-r from-orange-600 to-purple-600 transition-all duration-300 ${isHovered ? 'h-0.5' : 'h-px'}`} />
    </a>;
};

When incorporating Para into React Native or Expo applications, developers may face specific hurdles. This guide offers
solutions to common problems and provides best practices for a smooth integration process.

<Tip>
  Using an LLM (ChatGPT, Claude) or Coding Assistant (Cursor, Github Copilot)? Here are a few tips:

  1. Include the <Link label="Para LLM-optimized context file" href="https://docs.getpara.com/llms-full.txt" /> for the most up-to-date help
  2. Check out the <Link label="Example Hub Wiki" href="https://deepwiki.com/getpara/examples-hub" /> for an interactive LLM using Para Examples Hub
</Tip>

## General Troubleshooting Steps

Before addressing specific issues, try these general troubleshooting steps for both React Native and Expo projects:

<AccordionGroup>
  <Accordion title="Clear Cache and Dependencies">
    ```bash theme={null}
    # For React Native
    rm -rf node_modules
    npm cache clean --force
    npm install

    # For Expo
    expo r -c
    ```
  </Accordion>

  <Accordion title="Rebuild iOS and Android folders (Expo)">
    `bash expo prebuild --clean `
  </Accordion>

  <Accordion title="Rebuild the project">
    ```bash theme={null}
    # For React Native
    npx react-native run-ios
    npx react-native run-android

    # For Expo
    expo run:ios
    expo run:android
    ```
  </Accordion>
</AccordionGroup>

## Passkey Error Codes

The React Native SDK provides structured passkey error handling through `ParaPasskeyError`. Every passkey operation
throws a typed error with a machine-readable code, platform detection, and an actionable suggestion. See the
<Link label="Passkey Error Codes" href="/v2/react-native/error-codes" /> reference for the full list of error codes
and platform-specific troubleshooting steps.

## Common Issues and Solutions

<AccordionGroup>
  <Accordion title="Missing Polyfills">
    **Error**: Errors related to missing modules like `crypto`, `buffer`, or `stream`.

    **Solution**: Update your `metro.config.js` to include necessary polyfills:

    ```javascript theme={null}
    const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");
    const nodeLibs = require("node-libs-react-native");

    const config = {
      resolver: {
        extraNodeModules: {
          ...nodeLibs,
          crypto: require.resolve("react-native-quick-crypto"),
          buffer: require.resolve("@craftzdog/react-native-buffer"),
        },
      },
    };

    module.exports = mergeConfig(getDefaultConfig(__dirname), config);
    ```
  </Accordion>

  <Accordion title="Incomplete Shims">
    **Error**: Errors persist despite Metro configuration, often related to global objects.

    **Solution**: Create a `shim.js` file at the root of your project and import it in your entry file.

    For the complete `shim.js` setup, refer to the Polyfills and Shims section in the <Link label="React Native" href="/v2/react-native/setup/react-native" /> and <Link label="Expo" href="/v2/react-native/setup/expo" /> setup guides.
  </Accordion>

  <Accordion title="Missing Crypto Subtle API">
    **Error**: Errors related to `crypto.subtle` API or missing cryptographic functions.

    **Solution**: Add the `PolyfillCrypto` component to your root `App` component.

    ````jsx theme={null}
    import PolyfillCrypto from "react-native-webview-crypto";

    export default function App() {
    return (
    <>
      <PolyfillCrypto />
      {/* Your app components */}
    </>
    );
    }

    </Accordion>

    <Accordion title="WebCredentials Configuration">
    **Error**: Passkey functionality not working. Errors related to `ASAuthorizationController` or `ASWebAuthenticationSession` on iOS and `CredentialManager` on Android.

    **Solution**:
    Passkeys requires configuring both the iOS and Android environments with the Para associated domains and web credentials.
    Please check Step one of the Project Setup section for the <Link label="React Native" href="/v2/react-native/setup/react-native#add-para-shim" /> and <Link label="Expo" href="/v2/react-native/setup/expo#import-required-shims" /> setup guides for detailed instructions.

    </Accordion>

    <Accordion title="Apple App Site Association">
    **Error**: Passkeys not functioning despite correct configuration.

    **Solution**: Ensure your app's bundle identifier and team ID are registered with Para.

    <Info>
    Contact Para support to associate your app correctly. Provide your app's bundle identifier and team ID. You can find your team ID in the Apple Developer portal.
    </Info>

    </Accordion>

    <Accordion title='Android: "RP ID cannot be validated" (Error 50152)'>
    **Error**: `{"error": "Native error", "message": "Error: [50152] RP ID cannot be validated."}`

    This is an Android-specific error from Google Play Services indicating your app's signing certificate doesn't match what's registered in the Digital Asset Links for Para's domain.

    **Common causes:**
    - **Debug vs release key mismatch**: Debug builds use `~/.android/debug.keystore` while release builds use your production keystore. The SHA-256 fingerprint registered in the Developer Portal must match the keystore used to sign the build you're testing.
    - **Verification still pending**: After registering your SHA-256 fingerprint, Google can take up to 24 hours to verify. Check the status in the <Link label="Developer Portal" href="https://developer.getpara.com" /> under your API key's Native Passkey Configuration.
    - **Incorrect fingerprint**: Verify you copied the correct SHA-256 fingerprint (not SHA-1 or MD5).

    **Solution**: Get the correct fingerprint for your current build type and register it in the Developer Portal:
    ```bash
    # Debug builds
    keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

    # Release builds
    keytool -list -v -keystore <your_keystore_path>
    ````

    You can register both debug and release fingerprints in the Developer Portal to avoid this issue across build types.
  </Accordion>

  <Accordion title="Android: User Cancelled / No Credentials Available">
    **Error**: `UserCancelled` or `NoCredentials`

    **Solutions:**

    * `UserCancelled`: The user dismissed the passkey prompt. This is expected behavior — handle it gracefully in your app by catching the error and allowing the user to retry.
    * `NoCredentials`: No passkeys are stored on this device for the user. This typically means the user hasn't registered a passkey yet or is on a different device than where the passkey was created. Ensure your auth flow calls `registerPasskey()` for new users before attempting `loginWithPasskey()`.
  </Accordion>

  <Accordion title="iOS: Passkey Request Failed (Error 1004)">
    **Error**: `RequestFailed` from ASAuthorization

    This iOS error indicates the passkey operation failed at the system level.

    **Common causes:**

    * The associated domains entitlement is not configured correctly in Xcode (or `app.json` for Expo).
    * Your `teamId + bundleIdentifier` is not registered with Para.
    * The device cannot reach Apple's CDN to validate the Apple App Site Association file.

    **Solution**: Verify your associated domains are set to `webcredentials:app.beta.usecapsule.com` and `webcredentials:app.usecapsule.com`, and confirm your Team ID + Bundle ID is registered in the <Link label="Developer Portal" href="https://developer.getpara.com" />.
  </Accordion>

  <Accordion title="Keychain Decryption Error After Rebuild">
    **Error**: `com.oblador.keychain.exceptions.CryptoFailedException: Decryption failed: Authentication tag verification failed.`

    This is expected during development when you rebuild or reinstall the app. The previous keychain data was encrypted with a key tied to the old app installation.

    **Solution**: Clear the app data or uninstall and reinstall the app. This will not affect production users since they won't be reinstalling the app during normal use.
  </Accordion>

  <Accordion title="Expo Go Limitations">
    **Error**: Native modules not working in Expo Go.

    **Solution**: Para is reliant on native modules and will not work with Expo Go. Use Expo's build service to create a standalone app. You can do this by running `expo build:ios` or `expo build:android`. This will create the corresponding iOS or Android folders in your project and link the native modules correctly. Alternative use expo prebuild to create the native folders for both platforms.
  </Accordion>

  <Accordion title="Pod Linking Issues">
    **Error**: Native modules not linking correctly. Build errors related to missing pods. Build stalls at the linking stage.

    **Solution**: iOS in React Native projects requires manual linking of pods. Ensure the pods are correctly linked by running `pod install` in the `ios` directory. Expo auto links the pods, but you can run `expo prebuild --clean` to ensure the pods are correctly linked.

    ```bash theme={null}
    cd ios
    pod install
    cd ..
    npx react-native run-ios
    ```
  </Accordion>

  <Accordion title="Storage-Related Errors">
    **Error**: Errors retrieving stored items.

    **Solution**: Ensure React Native Async Storage and Keychain are installed and linked. Additionally ensure that you run `para.init()` as it asynchronusly initializes the storage.
  </Accordion>
</AccordionGroup>

### Best Practices

1. Implement robust error handling for all Para operations.
2. Use secure storage methods for sensitive data.
3. Keep your project's native code up to date with the latest Para SDK requirements.

For comprehensive setup instructions and the most up-to-date integration guide, please refer to our <Link label="React Native" href="/v2/react-native/setup/react-native" /> and <Link label="Expo" href="/v2/react-native/setup/expo" /> quick start guides.

### Integration Support

If you're experiencing issues that aren't resolved by our troubleshooting resources, please [contact our team](https://join.slack.com/t/para-community/shared_invite/zt-304keeulc-Oqs4eusCUAJEpE9DBwAqrg) for
assistance. To help us resolve your issue quickly, please include the following information in your request:

<ol className="space-y-4 list-none pl-0">
  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      1
    </span>

    <p className="flex-1 my-0">A detailed description of the problem you're encountering.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      2
    </span>

    <p className="flex-1 my-0">Any relevant error messages or logs.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      3
    </span>

    <p className="flex-1 my-0">Steps to reproduce the issue.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      4
    </span>

    <p className="flex-1 my-0">Details about your system or environment (e.g., device, operating system, software version).</p>
  </li>
</ol>

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