Troubleshooting

Available on: iOS Android Web

This guide covers common issues you might encounter when integrating the Genius Scan SDK, along with their solutions. For platform-specific troubleshooting, see the dedicated guides:

Common Issues

Expired License

One of the most common issues across all platforms is an expired license.

In case of an expired license, the various SDK methods will raise GSKError with the code GSKLicenseError. You can catch it and handle it as desired:

do {
    // SDK method call
} catch let error as GSKError where error.code == .licenseError {
    // Handle expired license
    // Prompt users to update to the latest version of your app
}

In case of an expired license, the various SDK methods will raise a LicenseException with an error code explaining the reason:

try {
    // SDK method call
} catch (LicenseException e) {
    // Handle expired license based on error code
    // e.getErrorCode() provides details (expired, invalid, demo ended, etc.)
    // Prompt users to update or fallback to another capture method
}

Solution: Update your license key or prompt users to update to the latest version of your app that includes a valid license.

SDK Integration Issues

Framework/Library Not Found

This typically occurs when the SDK files are not properly included in your project.

Error: 'image not found' error at launch

Solution: Ensure you included the frameworks GSSDKCore.xcframework (and optionally GSSDKScanFlow.xcframework, GSSDKOCR.xcframework) in the Embedded Binaries section of your project.

Error: ClassNotFoundException or similar runtime errors

Solution: Verify that the SDK AAR files are properly included in your build.gradle dependencies and that the repository sources are correctly configured.

Build Architecture Issues

Error:

ld: warning: ignoring file GSSDKOCR.framework/GSSDKOCR, building for iOS Simulator-arm64
but attempting to link with file built for iOS Simulator-x86_64

Solution: The Genius Scan SDK doesn’t support ARM Mac simulator targets. Exclude the arm64 architecture for simulator builds in your Xcode project settings.

Exclude arm64 for simulator

Error: Build failures related to native libraries or architecture mismatches

Solution: Ensure your build.gradle specifies the correct abiFilters if you’re targeting specific architectures, or remove filters to include all supported architectures.

UI and Localization Issues

Localization Not Working

Issue: The ScanFlow UI is not localized and appears in English regardless of device locale.

Solution:

  1. Applications must be localized in Xcode by adding each language to the project
  2. There must be at least one file localized in the Xcode project for the language to be properly picked up
  3. The framework will use the localization of the main app

The ScanFlow UI supports around 20 languages and automatically uses the device’s locale.

Issue: SDK UI elements appear in the wrong language.

Solution: Ensure your app properly declares supported locales in your resources and that the Android system can match the device locale to your app’s available translations.

Status Bar Issues (iOS)

Issue: The status bar appearance is broken in the scan flow.

Solution: The Genius Scan SDK only supports the modern, view controller-based status bar appearance introduced with iOS 7. You must:

  • Remove UIViewControllerBasedStatusBarAppearance=NO from your app’s Info.plist, or
  • Set it to YES

The camera screen is designed to work with the status bar hidden.

Performance and Size Issues

APK Size Too Large (Android)

Issue: The APK size is significantly larger than expected after including the SDK.

Root Cause: Native debug symbols are included as part of the SDK and should be removed for release builds.

Solution:

  1. Verify that Gradle runs the stripReleaseDebugSymbols task automatically
  2. Check build logs for warnings like:
    • Execution failed for task ':app:stripReleaseDebugSymbols'
    • Unable to strip the following libraries: libgssdk-core.so, libgssdk-ocr.so
  3. If issues occur, verify:
    • The Android NDK is installed: Android Studio > Settings > Android SDK > SDK Tools
    • NDK version matches the ndkVersion in your android/build.gradle file

Getting Further Help

If you continue to experience issues:

  1. Check the platform-specific guides for more detailed troubleshooting:
  2. Review the integration guides to ensure proper setup:
  3. Contact support with:
    • Your license key
    • Platform and version information
    • Complete error messages and stack traces
    • Steps to reproduce the issue

Common Error Patterns

  • Expired license exceptions/errors
  • Invalid license key format
  • Demo session limits exceeded

Integration Errors

  • Missing framework/library files
  • Incorrect build configuration
  • Architecture mismatches

Runtime Issues

  • Memory constraints during scanning
  • Camera permission problems
  • File system access issues

UI Problems

  • Localization not working
  • Status bar appearance issues
  • Custom theming conflicts

Each of these patterns has specific solutions detailed in the platform-specific troubleshooting guides.

Products

Industries

Case Studies

Integration

Company

© 2025 The Grizzly Labs. All rights reserved.