> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter Troubleshooting Guide

> Common issues and solutions when integrating Para with Flutter applications

export const Link = ({href, label, newTab = false}) => {
  const [isHovered, setIsHovered] = useState(false);
  return <a href={href} target={newTab ? '_blank' : '_self'} rel={newTab ? 'noopener noreferrer' : undefined} className="not-prose inline-block relative text-black font-semibold cursor-pointer border-b-0 no-underline" onMouseEnter={() => setIsHovered(true)} onMouseLeave={() => setIsHovered(false)}>
      {label}
      <span className={`absolute left-0 bottom-0 w-full rounded-sm bg-gradient-to-r from-orange-600 to-purple-600 transition-all duration-300 ${isHovered ? 'h-0.5' : 'h-px'}`} />
    </a>;
};

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.

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

  1. Include the <Link label="Para LLM-optimized context file" href="https://docs.getpara.com/llms-full.txt" /> for the most up-to-date help
  2. Check out the <Link label="Example Hub Wiki" href="https://deepwiki.com/getpara/examples-hub" /> for an interactive LLM using Para Examples Hub
</Tip>

## General Troubleshooting Steps

Before diving into specific issues, try these general troubleshooting steps:

1. **Clean the project and get dependencies**:

   ```bash theme={null}
   flutter clean
   flutter pub get
   ```

2. **Update Flutter and dependencies**:

   ```bash theme={null}
   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**:
   ```bash theme={null}
   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:

```yaml theme={null}
dependencies:
  flutter:
    sdk: flutter
  para: ^latest_version

dependency_overrides:
  # Add any necessary overrides here
```

After updating `pubspec.yaml`, run:

```bash theme={null}
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`):

```xml theme={null}
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>para</string>
    </array>
  </dict>
</array>
```

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

```gradle theme={null}
android {
    defaultConfig {
        ...
        minSdkVersion 21
    }
}
```

### 3. SDK Initialization Errors

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

**Solution**: Ensure proper initialization with required `appScheme` parameter:

```dart theme={null}
import 'package:para/para.dart';

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

  final para = Para.fromConfig(
    config: ParaConfig(
      environment: Environment.beta,
      apiKey: 'YOUR_API_KEY',
    ),
    appScheme: 'yourapp', // Required for deep links
  );

  runApp(MyApp(para: para));
}
```

**Common Initialization Issues**:

* Missing `appScheme` parameter
* Incorrect environment configuration
* Invalid API key format

### 4. ParaFuture Handling Errors

**Problem**: Errors when handling `ParaFuture` operations.

**Solution**: Ensure proper `ParaFuture` handling with cancellation support:

```dart theme={null}
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 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:

```dart theme={null}
import 'package:flutter/foundation.dart';

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

Future<Wallet> _createWallet(Para para) async {
  final walletFuture = para.createWallet(
    type: WalletType.evm,
    skipDistribute: false,
  );
  return await walletFuture.future;
}

// 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.

## SDK-Specific Issues

### 7. Authentication Flow Errors

**Problem**: Authentication flow failing or returning unexpected states.

**Solution**: Follow the correct authentication pattern:

```dart theme={null}
// Correct flow
final authState = await para.initiateAuthFlow(
  auth: Auth.email('user@example.com')
);

switch (authState.stage) {
  case AuthStage.verify:
    // Handle verification
    final verifiedState = await para.verifyOtp(
      otp: code
    );
    if (verifiedState.stage == AuthStage.signup) {
      final wallet = await para.handleSignup(
        authState: verifiedState,
        method: SignupMethod.passkey,
      );
    }
    break;

  case AuthStage.login:
    // Handle login
    final wallet = await para.handleLogin(
      authState: authState,
    );
    break;
}
```

### 8. OAuth Integration Issues

**Problem**: OAuth flows failing or not redirecting properly.

**Solution**: Ensure deep link configuration matches OAuth setup:

```dart theme={null}
// Correct OAuth flow
final authState = await para.verifyOAuth(
  provider: OAuthMethod.google,
  appScheme: 'yourapp', // Must match your URL scheme
);
```

### 9. Extension Methods Not Found

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

**Solution**: Import the auth extensions:

```dart theme={null}
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

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:
   ```dart theme={null}
   try {
     // Para operation
   } on ParaBridgeException catch (e) {
     // Handle Para-specific errors
   } catch (e) {
     // Handle general errors
   }
   ```

3. **Session Management**: Use session methods for persistence:
   ```dart theme={null}
   final isActive = await para.isSessionActive().future;
   if (!isActive) {
     // Show login screen
   }
   ```

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

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

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

7. **Performance Monitoring**: Monitor `ParaFuture` operations for performance.

8. **Keep Updated**: Regularly update to the latest SDK changes.

## Debugging Tips

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

   ```dart theme={null}
   Para.fromConfig(
     config: ParaConfig(
       environment: Environment.beta,
       apiKey: 'YOUR_API_KEY',
       logLevel: ParaLogLevel.verbose,
     ),
     appScheme: 'yourapp',
   );
   ```

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.

## Setup and Integration Issues

<AccordionGroup>
  <Accordion title="Para SDK initialization fails">
    If you're having trouble initializing the Para SDK:

    * Ensure you're providing the required `appScheme` parameter
    * Verify that you're using the correct API key and environment
    * Check that all necessary dependencies are installed properly
    * Look for any Dart errors in your Flutter debug console
    * Verify that your Flutter version is compatible with the Para SDK
  </Accordion>

  <Accordion title="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 iOS project
    * For Android, check that you've configured your `build.gradle` file with the namespace fix
    * Make sure you've provided the correct SHA-256 fingerprint to the Para team for Android
    * Ensure that biometric authentication is enabled on the test device
    * For Android, confirm the test device has a Google account signed in
    * Check that `WebAuthenticationSession` is properly configured
  </Accordion>

  <Accordion title="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 client initialization
    * Verify you're using the correct environment (`beta` or `prod`) that matches your API key
    * Ensure your account has the necessary permissions for the operations you're attempting
    * Check that your deep link scheme matches what's configured in your app
    * Verify the authentication flow is being followed correctly (verify → signup/login)
  </Accordion>

  <Accordion title="V2 Migration Issues">
    If you're migrating from V1 to V2:

    * Replace `signUpOrLogIn()` with `initiateAuthFlow()`
    * Replace `verifyNewAccount()` with `verifyOtp()`
    * Replace `loginWithPasskey()` with `handleLogin()`
    * Remove calls to `init()` - it no longer exists
    * Update constructor to use `Para.fromConfig()` factory method
    * Add the required `appScheme` parameter (now without ://callback suffix)
    * Update wallet creation to use `handleSignup()` with `SignupMethod.passkey` or `.password`
  </Accordion>
</AccordionGroup>

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](https://join.slack.com/t/para-community/shared_invite/zt-304keeulc-Oqs4eusCUAJEpE9DBwAqrg) for
assistance. To help us resolve your issue quickly, please include the following information in your request:

<ol className="space-y-4 list-none pl-0">
  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      1
    </span>

    <p className="flex-1 my-0">A detailed description of the problem you're encountering.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      2
    </span>

    <p className="flex-1 my-0">Any relevant error messages or logs.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      3
    </span>

    <p className="flex-1 my-0">Steps to reproduce the issue.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      4
    </span>

    <p className="flex-1 my-0">Details about your system or environment (e.g., device, operating system, software version).</p>
  </li>
</ol>

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