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 for the most up-to-date help
Check out the for an interactive LLM using 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 VersionsFor 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 {
  let result = try await paraManager.signTransaction(
    walletId: walletId,
    transaction: transaction
  )
} catch let error as ParaError {
  print("Transaction signing failed: \(error.description)")
}

Transaction Signing Errors

Error: Transaction signing failures

Solution: Handle signing errors appropriately:

do {
  let result = try await paraManager.signTransaction(
    walletId: wallet.id,
    transaction: transaction
  )
  print("Signed transaction: \(result.signedTransaction)")
} catch ParaError.bridgeError(let message) {
  print("Signing failed: \(message)")
} catch {
  print("Unexpected error: \(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

User Feedback

Logging

Secure Key Management

Async Operations

Retry Mechanisms

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

Setup and Integration Issues

Para SDK initialization fails

Passkey operations fail or throw errors

Authentication fails or API requests are rejected

Deep linking not working

Getting Help

If you’re still experiencing issues after trying the solutions above, you can get additional help:

Contact Para Support via or Slack
When reporting issues, include:
- Detailed error messages
- Steps to reproduce the issue
- Device and iOS version details
- Para SDK version

Getting Started

Framework Setup

Authentication & Users

External Wallets

Web3 Library Guides

Reference & Support

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

Setup and Integration Issues

Getting Help

Getting Started

Framework Setup

Authentication & Users

External Wallets

Web3 Library Guides

Reference & Support

​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

​Setup and Integration Issues

​Getting Help

General Troubleshooting Steps

Common Issues and Solutions

Authentication Issues

Transaction Signing Issues

Network Issues

External Wallet Issues

Best Practices

Development Tools

Setup and Integration Issues

Getting Help