This guide addresses common issues you might encounter when integrating Para with your Flutter application. It provides solutions and best practices to ensure a smooth integration.

Using an LLM (ChatGPT, Claude) or Coding Assistant (Cursor, Github Copilot)? Here are a few tips:

  1. Include the Para LLM-optimized context file to ensure you’re getting the most up-to-date help!
  2. 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 general troubleshooting steps:

  1. Clean the project and get dependencies:

    flutter clean
flutter pub get

  2. Update Flutter and dependencies:

    flutter upgrade
flutter pub upgrade

  3. Ensure Para package is up to date: Check your pubspec.yaml file and update the Para package version if necessary.

  4. Rebuild the project:

    flutter run

​
Common Issues and Solutions

​
1. Package Not Found or Version Conflicts

Problem: Dart can’t find the Para package or there are version conflicts with other dependencies.

Solution: Ensure your pubspec.yaml file is correctly configured:

dependencies:
  flutter:
    sdk: flutter
  para: ^latest_version

dependency_overrides:
  # Add any necessary overrides here

After updating pubspec.yaml, run:

flutter pub get

​
2. Platform-Specific Setup Issues

Problem: Para features not working on specific platforms (iOS/Android).

Solution: Ensure platform-specific configurations are correct:

For iOS (ios/Runner/Info.plist):

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>para</string>
    </array>
  </dict>
</array>

For Android (android/app/build.gradle):

android {
    defaultConfig {
        ...
        minSdkVersion 21
    }
}

​
3. V2 API Initialization Errors

Problem: Para v2 fails to initialize or throws errors on startup.

Solution: Ensure proper initialization with required deepLinkScheme parameter:

import 'package:para/para.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final para = Para(
    environment: Environment.beta,
    apiKey: 'YOUR_API_KEY',
    deepLinkScheme: 'yourapp://callback', // Required in v2!
  );

  runApp(MyApp(para: para));
}

Common v2 Initialization Issues:

  • Missing deepLinkScheme parameter
  • Incorrect environment configuration
  • Invalid API key format

​
4. V2 API ParaFuture Handling Errors

Problem: Errors when handling ParaFuture operations in v2 API.

Solution: Ensure proper ParaFuture handling with cancellation support:

try {
  final walletFuture = para.createWallet(
    type: WalletType.evm,
    skipDistribute: false,
  );
  
  // Handle the ParaFuture properly
  final wallet = await walletFuture.future;
  print('Wallet created: ${wallet.address}');
  
  // Cancel if needed
  // await para.cancelOperationById(walletFuture.requestId);
} catch (e) {
  print('Error creating wallet: $e');
  // Handle ParaBridgeException specifically
  if (e is ParaBridgeException) {
    print('Bridge error code: ${e.code}');
  }
}

Common v2 ParaFuture Issues:

  • Not awaiting the .future property
  • Incorrect cancellation handling
  • Missing error type checking for ParaBridgeException

​
5. UI Thread Blocking

Problem: Para operations blocking the UI thread.

Solution: Use compute function for heavy computations:

import 'package:flutter/foundation.dart';

Future<Wallet> createWalletAsync(Para para) async {
  return compute(_createWallet, para);
}

Wallet _createWallet(Para para) {
  return para.createWallet({skipDistribute: false});
}

// Usage
final wallet = await createWalletAsync(para);

​
6. Platform Channel Errors

Problem: Errors related to platform channel communication.

Solution: Ensure the latest version of Para Flutter plugin is used and platform-specific code is correctly implemented. If issues persist, check the plugin’s GitHub repository for any known issues or updates.

​
V2-Specific Issues

​
7. Authentication Flow Errors

Problem: V2 authentication flow failing or returning unexpected states.

Solution: Follow the correct v2 authentication pattern:

// Correct v2 flow
final authState = await para.signUpOrLogIn(
  auth: {'email': 'user@example.com'}
);

switch (authState.stage) {
  case AuthStage.verify:
    // Handle verification
    final verifiedFuture = para.verifyNewAccount(
      verificationCode: code
    );
    final verified = await verifiedFuture.future;
    break;
    
  case AuthStage.login:
    // Handle login
    final walletFuture = para.loginWithPasskey(email: authState.email);
    final wallet = await walletFuture.future;
    break;
}

​
8. OAuth Integration Issues

Problem: OAuth flows failing or not redirecting properly.

Solution: Ensure deep link configuration matches OAuth setup:

// Correct OAuth flow
final authState = await para.verifyOAuth(
  provider: OAuthMethod.google,
  deeplinkUrl: 'yourapp://callback', // Must match your URL scheme
);

​
9. Extension Methods Not Found

Problem: initiateAuthFlow() or other extension methods not available.

Solution: Import the auth extensions:

import 'package:para/para.dart';
import 'package:para/src/auth_extensions.dart'; // Required for extension methods

// Now you can use
final authState = await para.initiateAuthFlow(
  auth: Auth.email('user@example.com')
);

​
Best Practices for V2

  1. Use ParaFuture Properly: Always await the .future property and handle cancellation where appropriate.

  2. Error Handling: Implement robust error handling with specific exception types:

    try {
  // Para operation
} on ParaBridgeException catch (e) {
  // Handle Para-specific errors
} catch (e) {
  // Handle general errors
}

  3. Session Management: Use v2 session methods for persistence:

    final isActive = await para.isSessionActive();
if (!isActive) {
  // Show login screen
}

  4. State Management: Use proper state management for v2 authentication flows.

  5. Deep Link Security: Validate deep link callbacks to prevent malicious redirects.

  6. Testing: Write unit and integration tests for your Para v2 integration.

  7. Performance Monitoring: Monitor ParaFuture operations for performance.

  8. Keep Updated: Regularly update to the latest v2 API changes.

​
Debugging Tips

  1. Enable Verbose Logging: Enable verbose logging for Para operations to get more detailed information:

    Para(
  environment: Environment.beta,
  apiKey: 'YOUR_API_KEY',
  logLevel: ParaLogLevel.verbose,
);

  2. Use Flutter DevTools: Utilize Flutter DevTools for performance profiling and debugging.

  3. Platform-Specific Debugging: For platform-specific issues, use Xcode for iOS and Android Studio for Android debugging.

By following these troubleshooting steps and best practices, you should be able to resolve most common issues when integrating Para with your Flutter application.

​
Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:

  1. 1

    A detailed description of the problem you’re encountering.

  2. 2

    Any relevant error messages or logs.

  3. 3

    Steps to reproduce the issue.

  4. 4

    Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.