> ## 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.

# Troubleshooting

> Solutions for common issues with the Para Swift SDK integration

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>;
};

This guide helps you identify and resolve common issues encountered while integrating the Para Swift SDK into your iOS application.

<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 diving into specific issues, try these basic troubleshooting steps:

<Steps>
  <Step title="Clean Build Folder">
    In Xcode, go to **Product → Clean Build Folder** (Option + Shift + Command + K).
  </Step>

  <Step title="Update Dependencies">
    For Swift Package Manager: **File → Packages → Update to Latest Package Versions**

    For CocoaPods: Run `pod update` in your terminal.
  </Step>

  <Step title="Verify SDK Version">
    Ensure you are using the latest Para SDK compatible with your minimum deployment target (iOS 13.0+).
  </Step>

  <Step title="Check Configuration">
    Confirm your API key, Associated Domains, custom URL scheme, Team ID, and Bundle ID are correctly configured.
  </Step>
</Steps>

## Common Issues and Solutions

### Authentication Issues

<AccordionGroup>
  <Accordion title="Passkey Generation Failure">
    <Info>
      **Error:** `ParaError.bridgeError` or system authentication errors
    </Info>

    **Solution:** Verify Associated Domains, Team ID, Bundle ID, and domain setup.

    ```swift theme={null}
    do {
      try await paraManager.generatePasskey(
        identifier: email,
        biometricsId: biometricsId,
        authorizationController: authorizationController
      )
    } catch let error as ParaError {
      print("Para error occurred: \(error.description)")
    } catch let error as ASAuthorizationError {
      print("Authentication error: \(error.localizedDescription)")
    }
    ```
  </Accordion>

  <Accordion title="Biometric Authentication Failure">
    **Solution:** Confirm biometric setup on the device and check permissions in app settings.

    <Tip>
      Make sure your app includes the necessary privacy descriptions in Info.plist:

      * `NSFaceIDUsageDescription` for Face ID
      * Proper permission handling for biometric authentication
    </Tip>
  </Accordion>

  <Accordion title="User Cancellation">
    <Info>
      **Error:** `ASAuthorizationError.canceled` or similar system errors
    </Info>

    **Solution:** Catch authentication cancellation errors and offer a retry option to the user. This error occurs when the user cancels a biometric prompt.

    ```swift theme={null}
    do {
      try await paraManager.loginWithPasskey(authorizationController: authorizationController)
    } catch let error as ASAuthorizationError where error.code == .canceled {
      print("User canceled authentication")
    }
    ```
  </Accordion>

  <Accordion title="Email/Phone Verification Failure">
    **Solution:** Verify:

    * Correct environment settings (BETA/prod)
    * Proper user input (valid email/phone format)
    * Active network connection
    * You haven't hit rate limits for verification attempts
  </Accordion>
</AccordionGroup>

### Transaction Signing Issues

<AccordionGroup>
  <Accordion title="Invalid Transaction Format">
    <Info>
      **Error:** `ParaError.bridgeError` or `ParaError.error`
    </Info>

    **Solution:** Verify transaction parameters, proper encoding (Base64), and integration with web3 libraries.

    ```swift theme={null}
    do {
      let result = try await paraManager.signTransaction(
        walletId: walletId,
        transaction: transaction
      )
    } catch let error as ParaError {
      print("Transaction signing failed: \(error.description)")
    }
    ```
  </Accordion>

  <Accordion title="Transaction Signing Errors">
    <Info>
      **Error:** Transaction signing failures
    </Info>

    **Solution:** Handle signing errors appropriately:

    ```swift theme={null}
    do {
      let result = try await paraManager.signTransaction(
        walletId: wallet.id,
        transaction: transaction
      )
      print("Signed transaction: \(result.signedTransaction)")
    } catch ParaError.bridgeError(let message) {
      print("Signing failed: \(message)")
    } catch {
      print("Unexpected error: \(error)")
    }
    ```
  </Accordion>

  <Accordion title="Gas Estimation Issues">
    **Solution:**

    * Ensure wallet balance covers gas fees
    * Verify correct gas parameters
    * Use reliable web3 libraries for estimates
    * Consider implementing fallback gas values
  </Accordion>
</AccordionGroup>

### Network Issues

<AccordionGroup>
  <Accordion title="Connection Problems">
    <Info>
      **Error:** `ParaError.bridgeError` or `ParaError.bridgeTimeoutError`
    </Info>

    **Solution:** Check network connectivity, implement retry logic, and use network monitoring tools.

    ```swift theme={null}
    do {
      try await paraManager.createWallet(type: .evm, skipDistributable: false)
    } catch ParaError.bridgeTimeoutError {
      print("Bridge operation timed out. Check connectivity and try again.")
    } catch ParaError.bridgeError(let message) {
      print("Bridge error occurred: \(message)")
    }
    ```
  </Accordion>

  <Accordion title="Timeout Issues">
    <Info>
      **Error:** `ParaError.bridgeTimeoutError`
    </Info>

    **Solution:**

    * Implement timeout handling using Swift concurrency features
    * Provide retry options for users
    * Display loading indicators during network operations
    * Consider implementing exponential backoff for retries
  </Accordion>
</AccordionGroup>

### External Wallet Issues

<AccordionGroup>
  <Accordion title="MetaMask Connection Issues">
    <Info>
      **Error:** `MetaMaskError` or `ParaError.bridgeError`
    </Info>

    **Solution:** Check MetaMask installation and connection flow.

    ```swift theme={null}
    do {
      try await metaMaskConnector.connect()
    } catch let error as MetaMaskError {
      print("MetaMask error: \(error.localizedDescription)")
    } catch let error as ParaError {
      print("Para error during MetaMask connection: \(error.description)")
    }
    ```
  </Accordion>

  <Accordion title="External Wallet Login Failure">
    **Solution:** Confirm wallet address and type are correct for external wallet login.

    ```swift theme={null}
    do {
      let walletInfo = ExternalWalletInfo(
        address: walletAddress,
        type: .evm,
        provider: "metamask"
      )
      try await paraManager.loginExternalWallet(wallet: walletInfo)
    } catch let error as ParaError {
      print("External wallet login failed: \(error.description)")
    }
    ```
  </Accordion>

  <Accordion title="Deep Link Failures">
    **Solution:**

    * Verify URL schemes in `Info.plist`
    * Confirm deep-link handling in AppDelegate or SceneDelegate
    * Test with simple deep links to isolate the issue
    * Check if the external wallet app is properly installed
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Robust Error Handling" description="Implement comprehensive do-catch blocks to handle Para SDK errors gracefully." />

  <Card title="User Feedback" description="Provide clear, actionable feedback to users when errors occur." />

  <Card title="Logging" description="Implement detailed logging to help troubleshoot issues in production." />

  <Card title="Secure Key Management" description="Follow best practices for managing keys and sessions securely." />

  <Card title="Async Operations" description="Handle asynchronous operations properly with Swift concurrency." />

  <Card title="Retry Mechanisms" description="Implement smart retry logic for network operations and authentication." />
</CardGroup>

## Development Tools

<Steps>
  <Step title="Enable Debug Mode">
    Enable debug mode in the Para SDK (if available) to get more detailed logging information.
  </Step>

  <Step title="Network Debugging">
    Utilize network debugging tools like Charles Proxy or Xcode's network debugger to inspect API calls.
  </Step>

  <Step title="Xcode Debugging">
    Leverage Xcode's built-in debugging features:

    * Set breakpoints at critical points
    * Inspect variables and state
    * Use the console for logging
  </Step>
</Steps>

### Setup and Integration Issues

<AccordionGroup>
  <Accordion title="Para SDK initialization fails">
    If you're having trouble initializing the Para SDK:

    * Ensure you're providing the required `appScheme` parameter
    * Verify that you're using the correct API key and environment
    * Check that all necessary dependencies are installed properly
    * Look for any Swift compiler errors in your Xcode console
    * Verify that your minimum deployment target is iOS 13.0 or higher
  </Accordion>

  <Accordion title="Passkey operations fail or throw errors">
    If passkey creation, retrieval, or usage isn't working:

    * Verify that you've set up Associated Domains correctly in your Xcode project
    * Make sure you've registered your Team ID + Bundle ID with Para via the Developer Portal
    * Ensure that biometric authentication is enabled on the test device
    * Check that `AuthorizationController` is properly configured
    * Verify Face ID/Touch ID permissions are properly set in Info.plist
    * Check for `ASAuthorizationError.canceled` when users cancel the biometric prompt
  </Accordion>

  <Accordion title="Authentication fails or API requests are rejected">
    If you're experiencing authentication issues:

    * Double-check that your API key is correct and properly set in your Para manager initialization
    * Verify you're using the correct environment (`beta` or `prod`) that matches your API key
    * Ensure your account has the necessary permissions for the operations you're attempting
    * Check that your URL scheme matches what's configured in your Info.plist
    * Verify the authentication flow is being followed correctly (verify → signup/login)
  </Accordion>

  <Accordion title="Deep linking not working">
    If OAuth callbacks or deep links aren't functioning:

    * Verify your URL scheme is correctly configured in Info.plist
    * Check that `onOpenURL` modifier is properly implemented
    * Ensure the `appScheme` parameter matches your URL scheme exactly
    * Test with a simple deep link first to isolate the issue
    * Make sure your app is handling the URL in the main app file
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still experiencing issues after trying the solutions above, you can get additional help:

* <Link label="Para Documentation" href="/v3/introduction/welcome" />
* Contact Para Support via <Link label="email" href="mailto:support@getpara.com" /> or [Slack](https://join.slack.com/t/para-community/shared_invite/zt-304keeulc-Oqs4eusCUAJEpE9DBwAqrg)
* When reporting issues, include:
  * Detailed error messages
  * Steps to reproduce the issue
  * Device and iOS version details
  * Para SDK version