> ## Documentation Index
> Fetch the complete documentation index at: https://jdev-e8db0569.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for seon_orchestration_flutter.

## Installation Issues

### Pod Install Fails (iOS)

**Symptom:**

```
[!] CocoaPods could not find compatible versions for pod "SEONOrchSDK"
```

**Solutions:**

1. Ensure your minimum iOS version is 13.0 or higher in your Podfile:

```ruby theme={null}
platform :ios, '13.0'
```

2. Update your CocoaPods repository:

```bash theme={null}
cd ios
pod repo update
pod install
cd ..
```

3. If still failing, try clearing the cache:

```bash theme={null}
cd ios
rm -rf Pods
rm Podfile.lock
pod cache clean --all
pod install
cd ..
```

### Gradle Sync Fails (Android)

**Symptom:**

```
Could not find io.seon:orchestration-android-sdk
```

**Solutions:**

1. Ensure `mavenCentral()` is in your repositories in `android/build.gradle`:

```gradle theme={null}
allprojects {
    repositories {
        mavenCentral()
        google()
    }
}
```

2. Check that your `minSdkVersion` is at least 26:

```gradle theme={null}
android {
    defaultConfig {
        minSdkVersion 26
    }
}
```

3. Try cleaning and rebuilding:

```bash theme={null}
cd android
./gradlew clean
./gradlew build
cd ..
```

### Plugin Not Found

**Symptom:**

```
Could not resolve package 'seon_orchestration_flutter'
```

**Solutions:**

1. Verify your `pubspec.yaml` dependency is correct
2. Run `flutter pub get` again
3. If using a path dependency, verify the path is correct

***

## Runtime Errors

### "SEON SDK not initialized" Error

**Symptom:**

```
SeonException(eNotInitialized): SEON SDK has not been initialized. Call initialize() first.
```

**Solution:**

You must call `initialize()` before calling `startVerification()`. The SDK remains initialized across multiple verification flows until `dispose()` is called:

```dart theme={null}
// Initialize once
await SeonOrchestration.initialize(config);

// Can call startVerification() multiple times
final result = await SeonOrchestration.startVerification();

// When done, clean up resources
await SeonOrchestration.dispose();
```

Make sure initialization completes successfully before starting verification:

```dart theme={null}
Future<void> _handleVerify() async {
  try {
    await SeonOrchestration.initialize(config);
    final result = await SeonOrchestration.startVerification();
    // Handle result...
  } on SeonException catch (e) {
    debugPrint('Error: $e');
  }
}
```

### Missing Permissions

**Symptom:** Verification fails immediately or SDK requests permissions that crash the app.

<Tabs>
  <Tab title="iOS">
    Ensure all required keys are in `ios/Runner/Info.plist`:

    ```xml theme={null}
    <key>NSCameraUsageDescription</key>
    <string>We need camera access for identity verification</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>We need microphone access for identity verification</string>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>We need location access for identity verification</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>We need photo library access for identity verification</string>
    ```

    <Warning>Missing any of these will cause the app to crash when the SDK requests that permission.</Warning>
  </Tab>

  <Tab title="Android">
    Ensure all required permissions are in `android/app/src/main/AndroidManifest.xml`:

    ```xml theme={null}
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
                     android:maxSdkVersion="28" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
                     android:maxSdkVersion="32" />
    ```
  </Tab>
</Tabs>

***

## Device Testing Issues

### Camera/Location Not Working on Device

**Symptom:** Verification starts but camera or location features don't work.

**Solutions:**

1. **Handle permission denial in code:**

```dart theme={null}
final result = await SeonOrchestration.startVerification();
if (result.status == SeonVerificationStatus.missingLocationPermission) {
  showDialog(
    context: context,
    builder: (ctx) => AlertDialog(
      title: const Text('Permission Required'),
      content: const Text('Please enable location services in Settings'),
      actions: [
        TextButton(onPressed: () => Navigator.pop(ctx), child: const Text('Cancel')),
        TextButton(
          onPressed: () => openAppSettings(),
          child: const Text('Open Settings'),
        ),
      ],
    ),
  );
}
```

2. **Check device settings:**
   * iOS: Settings > Your App > Permissions
   * Android: Settings > Apps > Your App > Permissions

3. **Test on a different device** — some devices may have hardware or OS limitations.

### Build Fails on Simulator

**Symptom:** App builds and runs fine on device but fails on simulator.

**Solution:** The SEON SDKs require real device hardware. They are not designed to work on simulators or emulators.

<Warning>Always test on real physical devices (iPhone/iPad for iOS, Android phone/tablet for Android).</Warning>

If you need to develop without a device, you can mock the plugin in your app:

```dart theme={null}
// In your test/development code
if (kDebugMode) {
  debugPrint('Skipping verification in development');
  // Return mock result
}
```

***

## Debugging Tips

### Enable Verbose Logging

```dart theme={null}
debugPrint('Initializing SEON SDK...');
await SeonOrchestration.initialize(config);
debugPrint('SEON SDK initialized');

debugPrint('Starting verification...');
final result = await SeonOrchestration.startVerification();
debugPrint('Verification result: ${result.status}');
```

### Check Native Logs

<Tabs>
  <Tab title="iOS (Xcode)">
    1. Open your project in Xcode
    2. Run on device
    3. Check Console for native logs
  </Tab>

  <Tab title="Android (Logcat)">
    ```bash theme={null}
    adb logcat | grep -i seon
    ```
  </Tab>
</Tabs>

### Test Initialization Separately

Isolate initialization to narrow down issues:

```dart theme={null}
try {
  await SeonOrchestration.initialize(config);
  debugPrint('SUCCESS: Initialization completed');
} on SeonException catch (e) {
  debugPrint('FAILED: Initialization error: $e');
}
```

## Getting Help

If you're still experiencing issues:

1. Check the [API Reference](/api-reference/initialize) for correct usage
2. Review [Platform Notes](/guides/platform-notes) for platform-specific requirements
3. Check the [Architecture](/guides/architecture) doc to understand how the bridge works
4. Open an issue on GitHub with:
   * Flutter version
   * iOS/Android version
   * Error messages
   * Steps to reproduce