API & Troubleshooting
Troubleshooting
Solutions for common issues with the Para Swift SDK integration
This guide helps you identify and resolve common issues encountered while integrating the Para Swift SDK into your iOS application.
Solution: Verify Associated Domains, Team ID, Bundle ID, and domain setup.
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 transaction parameters, proper encoding (Base64), and integration with web3 libraries.
Solution: Inform the user clearly about what they’re signing and provide a retry option if they accidentally rejected the prompt.
Solution: Check network connectivity, implement retry logic, and use network monitoring tools.
Solution: Prompt users to install MetaMask from the App Store.
Using an LLM (ChatGPT, Claude) or Coding Assistant (Cursor, Github Copilot)? Here are a few tips:
- Include the Para LLM-optimized context file for the most up-to-date help
- 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
Passkey Generation Failure
Passkey Generation Failure
Error:
ParaError.passkeyGenerationFailedBiometric Authentication Failure
Biometric Authentication Failure
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:
NSFaceIDUsageDescriptionfor Face ID- Proper permission handling for biometric authentication
User Rejection
User Rejection
Error:
ParaError.userRejectedEmail/Phone Verification Failure
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
Transaction Signing Issues
Invalid Transaction Format
Invalid Transaction Format
Error:
ParaError.invalidTransactionUser Rejection (Signing)
User Rejection (Signing)
Error:
ParaError.userRejectedGas Estimation Issues
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
Network Issues
Connection Problems
Connection Problems
Error:
ParaError.networkErrorTimeout Issues
Timeout Issues
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
MetaMask Not Installed
MetaMask Not Installed
Error:
ParaError.walletNotInstalledMetaMask Connection Failure
MetaMask Connection Failure
Solution: Confirm URL scheme setup and correct handling of deep-link callbacks.
Deep Link Failures
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
Best Practices
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