Troubleshooting

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

Error: ParaError.bridgeError or system authentication errors

Solution: Verify Associated Domains, Team ID, Bundle ID, and domain setup.

do {
  try await paraManager.generatePasskey(
    identifier: email, 
    biometricsId: biometricsId, 
    authorizationController: authorizationController
  )
} catch let error as ParaError {
  print("Para error occurred: \(error.description)")
} catch let error as ASAuthorizationError {
  print("Authentication error: \(error.localizedDescription)")
}

Biometric Authentication Failure

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.

do {
  try await paraManager.loginWithPasskey(authorizationController: authorizationController)
} catch let error as ASAuthorizationError where error.code == .canceled {
  print("User canceled authentication")
}

Email/Phone Verification Failure

Transaction Signing Issues

Invalid Transaction Format

Error: ParaError.bridgeError or ParaError.error

Solution: Verify transaction parameters, proper encoding (Base64), and integration with web3 libraries.

do {
  try await paraEvmSigner.signTransaction(transactionB64: transaction.b64Encoded())
} catch let error as ParaError {
  print("Transaction signing failed: \(error.description)")
} catch let error as ParaSolanaSignerError {
  print("Solana signing error: \(error.localizedDescription)")
}

Signer Errors

Error: ParaSolanaSignerError for Solana operations

Solution: Handle specific signer errors appropriately:

do {
  try await paraSolanaSigner.signTransaction(transaction)
} catch ParaSolanaSignerError.missingWalletId {
  print("Wallet ID is missing. Call selectWallet() first.")
} catch ParaSolanaSignerError.invalidWalletType {
  print("Invalid wallet type for Solana operations.")
} catch ParaSolanaSignerError.signingFailed(let underlyingError) {
  print("Signing failed: \(underlyingError?.localizedDescription ?? "Unknown error")")
}

Gas Estimation Issues

Network Issues

Connection Problems

Error: ParaError.bridgeError or ParaError.bridgeTimeoutError

Solution: Check network connectivity, implement retry logic, and use network monitoring tools.

do {
  try await paraManager.createWallet(type: .evm, skipDistributable: false)
} catch ParaError.bridgeTimeoutError {
  print("Bridge operation timed out. Check connectivity and try again.")
} catch ParaError.bridgeError(let message) {
  print("Bridge error occurred: \(message)")
}

Timeout Issues

External Wallet Issues

MetaMask Connection Issues

Error: MetaMaskError or ParaError.bridgeError

Solution: Check MetaMask installation and connection flow.

do {
  try await metaMaskConnector.connect()
} catch let error as MetaMaskError {
  print("MetaMask error: \(error.localizedDescription)")
} catch let error as ParaError {
  print("Para error during MetaMask connection: \(error.description)")
}

External Wallet Login Failure

Solution: Confirm wallet address and type are correct for external wallet login.

do {
  let walletInfo = ExternalWalletInfo(
    address: walletAddress,
    type: .evm,
    provider: "metamask"
  )
  try await paraManager.loginExternalWallet(wallet: walletInfo)
} catch let error as ParaError {
  print("External wallet login failed: \(error.description)")
}

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

On this page

General Troubleshooting Steps
Common Issues and Solutions
Authentication Issues
Transaction Signing Issues
Network Issues
External Wallet Issues
Best Practices
Development Tools
Getting Help

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

Error: ParaError.bridgeError or system authentication errors

Solution: Verify Associated Domains, Team ID, Bundle ID, and domain setup.

do {
  try await paraManager.generatePasskey(
    identifier: email, 
    biometricsId: biometricsId, 
    authorizationController: authorizationController
  )
} catch let error as ParaError {
  print("Para error occurred: \(error.description)")
} catch let error as ASAuthorizationError {
  print("Authentication error: \(error.localizedDescription)")
}

Biometric Authentication Failure

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.

do {
  try await paraManager.loginWithPasskey(authorizationController: authorizationController)
} catch let error as ASAuthorizationError where error.code == .canceled {
  print("User canceled authentication")
}

Email/Phone Verification Failure

Transaction Signing Issues

Invalid Transaction Format

Error: ParaError.bridgeError or ParaError.error

Solution: Verify transaction parameters, proper encoding (Base64), and integration with web3 libraries.

do {
  try await paraEvmSigner.signTransaction(transactionB64: transaction.b64Encoded())
} catch let error as ParaError {
  print("Transaction signing failed: \(error.description)")
} catch let error as ParaSolanaSignerError {
  print("Solana signing error: \(error.localizedDescription)")
}

Signer Errors

Error: ParaSolanaSignerError for Solana operations

Solution: Handle specific signer errors appropriately:

do {
  try await paraSolanaSigner.signTransaction(transaction)
} catch ParaSolanaSignerError.missingWalletId {
  print("Wallet ID is missing. Call selectWallet() first.")
} catch ParaSolanaSignerError.invalidWalletType {
  print("Invalid wallet type for Solana operations.")
} catch ParaSolanaSignerError.signingFailed(let underlyingError) {
  print("Signing failed: \(underlyingError?.localizedDescription ?? "Unknown error")")
}

Gas Estimation Issues

Network Issues

Connection Problems

Error: ParaError.bridgeError or ParaError.bridgeTimeoutError

Solution: Check network connectivity, implement retry logic, and use network monitoring tools.

do {
  try await paraManager.createWallet(type: .evm, skipDistributable: false)
} catch ParaError.bridgeTimeoutError {
  print("Bridge operation timed out. Check connectivity and try again.")
} catch ParaError.bridgeError(let message) {
  print("Bridge error occurred: \(message)")
}

Timeout Issues

External Wallet Issues

MetaMask Connection Issues

Error: MetaMaskError or ParaError.bridgeError

Solution: Check MetaMask installation and connection flow.

do {
  try await metaMaskConnector.connect()
} catch let error as MetaMaskError {
  print("MetaMask error: \(error.localizedDescription)")
} catch let error as ParaError {
  print("Para error during MetaMask connection: \(error.description)")
}

External Wallet Login Failure

Solution: Confirm wallet address and type are correct for external wallet login.

do {
  let walletInfo = ExternalWalletInfo(
    address: walletAddress,
    type: .evm,
    provider: "metamask"
  )
  try await paraManager.loginExternalWallet(wallet: walletInfo)
} catch let error as ParaError {
  print("External wallet login failed: \(error.description)")
}

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

On this page

General Troubleshooting Steps
Common Issues and Solutions
Authentication Issues
Transaction Signing Issues
Network Issues
External Wallet Issues
Best Practices
Development Tools
Getting Help

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

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

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

General Troubleshooting Steps

Common Issues and Solutions

Authentication Issues

Transaction Signing Issues

Network Issues

External Wallet Issues

Best Practices

Development Tools

Getting Help