Skip to main content
This guide helps you identify and resolve common issues encountered while integrating the Para Swift SDK into your iOS application.
Using an LLM (ChatGPT, Claude) or Coding Assistant (Cursor, Github Copilot)? Here are a few tips:
  1. Include the for the most up-to-date help
  2. Check out the for an interactive LLM using Para Examples Hub

​
General Troubleshooting Steps

Before diving into specific issues, try these basic troubleshooting steps:
1

Clean Build Folder

In Xcode, go to Product → Clean Build Folder (Option + Shift + Command + K).
2

Update Dependencies

For Swift Package Manager: File → Packages → Update to Latest Package VersionsFor CocoaPods: Run pod update in your terminal.
3

Verify SDK Version

Ensure you are using the latest Para SDK compatible with your minimum deployment target (iOS 13.0+).
4

Check Configuration

Confirm your API key, Associated Domains, custom URL scheme, Team ID, and Bundle ID are correctly configured.

​
Common Issues and Solutions

​
Authentication Issues

Error: ParaError.bridgeError or system authentication errors
Solution: Verify Associated Domains, Team ID, Bundle ID, and domain setup.
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)")
}
Solution: Confirm biometric setup on the device and check permissions in app settings.
Make sure your app includes the necessary privacy descriptions in Info.plist:
  • NSFaceIDUsageDescription for Face ID
  • Proper permission handling for biometric authentication
Error: ASAuthorizationError.canceled or similar system errors
Solution: Catch authentication cancellation errors and offer a retry option to the user. This error occurs when the user cancels a biometric prompt.
do {
  try await paraManager.loginWithPasskey(authorizationController: authorizationController)
} catch let error as ASAuthorizationError where error.code == .canceled {
  print("User canceled authentication")
}
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

​
Transaction Signing Issues

Error: ParaError.bridgeError or ParaError.error
Solution: Verify transaction parameters, proper encoding (Base64), and integration with web3 libraries.
do {
  let result = try await paraManager.signTransaction(
    walletId: walletId,
    transaction: transaction
  )
} catch let error as ParaError {
  print("Transaction signing failed: \(error.description)")
}
Error: Transaction signing failures
Solution: Handle signing errors appropriately:
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)")
}
Solution:
  • Ensure wallet balance covers gas fees
  • Verify correct gas parameters
  • Use reliable web3 libraries for estimates
  • Consider implementing fallback gas values

​
Network Issues

Error: ParaError.bridgeError or ParaError.bridgeTimeoutError
Solution: Check network connectivity, implement retry logic, and use network monitoring tools.
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)")
}
Error: ParaError.bridgeTimeoutError
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

​
External Wallet Issues

Error: MetaMaskError or ParaError.bridgeError
Solution: Check MetaMask installation and connection flow.
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)")
}
Solution: Confirm wallet address and type are correct for external wallet login.
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)")
}

​
Best Practices

Robust Error Handling

User Feedback

Logging

Secure Key Management

Async Operations

Retry Mechanisms

​
Development Tools

1

Enable Debug Mode

Enable debug mode in the Para SDK (if available) to get more detailed logging information.
2

Network Debugging

Utilize network debugging tools like Charles Proxy or Xcode’s network debugger to inspect API calls.
3

Xcode Debugging

Leverage Xcode’s built-in debugging features:
  • Set breakpoints at critical points
  • Inspect variables and state
  • Use the console for logging

​
Setup and Integration Issues

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
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
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)
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

​
Getting Help

If you’re still experiencing issues after trying the solutions above, you can get additional help:
  • Contact Para Support via or Slack
  • When reporting issues, include:
    • Detailed error messages
    • Steps to reproduce the issue
    • Device and iOS version details
    • Para SDK version
⌘I