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, orYES
The 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.so
ndkVersion
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.