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.
Using an LLM (ChatGPT, Claude) or Coding Assistant (Cursor, Github Copilot)? Here are a few tips:
- Include the Para LLM-optimized context file to ensure you’re getting the most up-to-date help!
- Check out the Example Hub Wiki for an interactive LLM that leverages the Para Examples Hub!
General Troubleshooting Steps
Before diving into specific issues, try these basic troubleshooting steps:
Clean Build Folder
In Xcode, go to Product → Clean Build Folder (Option + Shift + Command + K).
Update Dependencies
For Swift Package Manager: File → Packages → Update to Latest Package Versions
For CocoaPods: Run pod update
in your terminal.
Verify SDK Version
Ensure you are using the latest Para SDK compatible with your minimum deployment target (iOS 13.0+).
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.bridgeError
or system authentication errors
Solution: Verify Associated Domains, Team ID, Bundle ID, and domain setup.
Biometric 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:
NSFaceIDUsageDescription
for Face ID- Proper permission handling for biometric authentication
User Cancellation
User Cancellation
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.
Email/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.bridgeError
or ParaError.error
Solution: Verify transaction parameters, proper encoding (Base64), and integration with web3 libraries.
Signer Errors
Signer Errors
Error: ParaSolanaSignerError
for Solana operations
Solution: Handle specific signer errors appropriately:
Gas 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.bridgeError
or ParaError.bridgeTimeoutError
Solution: Check network connectivity, implement retry logic, and use network monitoring tools.
Timeout Issues
Timeout Issues
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
MetaMask Connection Issues
MetaMask Connection Issues
Error: MetaMaskError
or ParaError.bridgeError
Solution: Check MetaMask installation and connection flow.
External Wallet Login Failure
External Wallet Login Failure
Solution: Confirm wallet address and type are correct for external wallet login.
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
Enable Debug Mode
Enable debug mode in the Para SDK (if available) to get more detailed logging information.
Network Debugging
Utilize network debugging tools like Charles Proxy or Xcode’s network debugger to inspect API calls.
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