Reference & Support
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 authentication cancellation errors and offer a retry option to the user. This error occurs when the user cancels a biometric prompt.
Solution: Verify transaction parameters, proper encoding (Base64), and integration with web3 libraries.
Solution: Handle specific signer errors appropriately:
Solution: Check network connectivity, implement retry logic, and use network monitoring tools.
Solution:
Solution: Check MetaMask installation and connection flow.
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.bridgeError or system authentication errorsBiometric 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 Cancellation
User Cancellation
Error:
ASAuthorizationError.canceled or similar system errorsEmail/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.errorSigner Errors
Signer Errors
Error:
ParaSolanaSignerError for Solana operationsGas 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.bridgeTimeoutErrorTimeout Issues
Timeout Issues
Error:
ParaError.bridgeTimeoutError- 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.bridgeErrorExternal 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
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
Para SDK initialization fails
Para SDK initialization fails
If you’re having trouble initializing the Para SDK:
- Ensure you’re providing the required
appSchemeparameter - 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
Passkey operations fail or throw errors
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
AuthorizationControlleris properly configured - Verify Face ID/Touch ID permissions are properly set in Info.plist
- Check for
ASAuthorizationError.canceledwhen users cancel the biometric prompt
Authentication fails or API requests are rejected
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 (
betaorprod) 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)
Deep linking not working
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
onOpenURLmodifier is properly implemented - Ensure the
appSchemeparameter 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