Troubleshooting

This guide helps you identify and resolve common issues encountered while integrating the Para Swift SDK into your iOS application.

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

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.")
}

Biometric Authentication Failure

User Rejection

Email/Phone Verification Failure

Transaction Signing Issues

Invalid Transaction Format

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.")
}

User Rejection (Signing)

Gas Estimation Issues

Network Issues

Connection Problems

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.")
}

Timeout Issues

External Wallet Issues

MetaMask Not Installed

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.")
}

MetaMask Connection Failure

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

Deep Link Failures

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

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

Introduction

Setup

Guides

API & Troubleshooting

Troubleshooting

General Troubleshooting Steps

Common Issues and Solutions

Authentication Issues

Transaction Signing Issues

Network Issues

External Wallet Issues

Best Practices

Robust Error Handling

User Feedback

Logging

Secure Key Management

Async Operations

Retry Mechanisms

Development Tools

Getting Help

Introduction

Setup

Guides

API & Troubleshooting

​General Troubleshooting Steps

​Common Issues and Solutions

​Authentication Issues

​Transaction Signing Issues

​Network Issues

​External Wallet Issues

​Best Practices

Robust Error Handling

User Feedback

Logging

Secure Key Management

Async Operations

Retry Mechanisms

​Development Tools

​Getting Help

General Troubleshooting Steps

Common Issues and Solutions

Authentication Issues

Transaction Signing Issues

Network Issues

External Wallet Issues

Best Practices

Development Tools

Getting Help