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:
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.
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.
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.
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.
Issue: The ScanFlow UI is not localized and appears in English regardless of device locale.
Solution:
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.
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:
UIViewControllerBasedStatusBarAppearance=NO from your app’s Info.plist, orYESThe camera screen is designed to work with the status bar hidden.
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:
stripReleaseDebugSymbols task automaticallyExecution failed for task ':app:stripReleaseDebugSymbols'Unable to strip the following libraries: libgssdk-core.so, libgssdk-ocr.sondkVersion in your android/build.gradle fileIf you continue to experience issues:
Each of these patterns has specific solutions detailed in the platform-specific troubleshooting guides.
© 2025 The Grizzly Labs. All rights reserved.