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 Para LLM-optimized context file for the most up-to-date help
  2. Check out the Example Hub Wiki 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.passkeyGenerationFailed
Solution: Verify Associated Domains, Team ID, Bundle ID, and domain setup.
do {
  try await paraManager.generatePasskey(
    identifier: email, 
    biometricsId: biometricsId, 
    authorizationController: authorizationController
  )
} catch ParaError.passkeyGenerationFailed {
  print("Passkey generation failed. Check configurations.")
}
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: ParaError.userRejected
Solution: Catch this error and offer a retry option to the user. This error occurs when the user cancels a biometric prompt or declines to allow the action.
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.invalidTransaction
Solution: Verify transaction parameters, proper encoding (Base64), and integration with web3 libraries.
do {
  try await paraEvmSigner.signTransaction(transactionB64: transaction.b64Encoded())
} catch ParaError.invalidTransaction {
  print("Transaction format is invalid. Check parameters and encoding.")
}
Error: ParaError.userRejected
Solution: Inform the user clearly about what they’re signing and provide a retry option if they accidentally rejected the prompt.
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.networkError
Solution: Check network connectivity, implement retry logic, and use network monitoring tools.
do {
  try await paraManager.createWallet(type: .evm, skipDistributable: false)
} catch ParaError.networkError {
  print("Network connection issue. Check connectivity and try again.")
}
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: ParaError.walletNotInstalled
Solution: Prompt users to install MetaMask from the App Store.
do {
  try await metaMaskConnector.connect()
} catch ParaError.walletNotInstalled {
  print("MetaMask is not installed. Please install it from the App Store.")
}
Solution: Confirm URL scheme setup and correct handling of deep-link callbacks.
// In your AppDelegate or Scene implementation
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
  guard let url = URLContexts.first?.url else { return }
  metaMaskConnector.handleURL(url)
}

​
Best Practices

Robust Error Handling

Implement comprehensive do-catch blocks to handle Para SDK errors gracefully.

User Feedback

Provide clear, actionable feedback to users when errors occur.

Logging

Implement detailed logging to help troubleshoot issues in production.

Secure Key Management

Follow best practices for managing keys and sessions securely.

Async Operations

Handle asynchronous operations properly with Swift concurrency.

Retry Mechanisms

Implement smart retry logic for network operations and authentication.

​
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

​
Getting Help

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