Troubleshooting Pixelnetica™ Document Scanning SDK for Android

The problems integrators actually hit, with their causes and fixes — from the first Gradle sync to release builds. Each section starts from the symptom you see. If yours is not here, the contacting support section says what to include so one message is enough.

Gradle Cannot Resolve the SDK

Symptoms: Could not resolve com.pixelnetica.sdk:scanning, 401 Unauthorized, or Received status code 401 from server during sync.

Likely cause: GitHub Packages requires authentication for every download, even though the packages themselves are not secret. The repository declaration is missing, the token is absent or expired, the token lacks the read:packages permission — or it is one of GitHub’s newer fine-grained tokens, which GitHub Packages does not accept.

Fix, if you want to stay on GitHub Packages: work through the GitHub Packages route. The maven block must point at https://maven.pkg.github.com/Pixelnetica/artifacts, and the credentials must be a GitHub user name plus a classic token with read:packages. Keep credentials in local.properties (as the demo application does), not in the build script. A 401 after it once worked usually means the token expired.

Fix, if you would rather not deal with tokens at all: switch the repository declaration to https://maven.pixelnetica.com/ and delete the credentials block — see Add to a project. Every 3.x release except 3.1.0 and the -SNAPSHOT versions resolves from there; those two stay on GitHub Packages, which keeps serving everything it already has.

A resolution failure that is not a 401 — no status code, or a 404 — usually means the version you asked for is one of the exceptions above. Check which versions are where.

Manifest Merger Fails on minSdk

Symptoms: uses-sdk:minSdkVersion XX cannot be smaller than version 23 declared in library [com.pixelnetica.sdk:scanning].

Likely cause: Your application’s minSdk is below the SDK’s floor of API level 23 (Android 6.0).

Fix: Raise minSdk to 23 or higher. There is no override that keeps a lower floor working — the SDK’s native layer needs API 23.

The App Crashes with UnsatisfiedLinkError

Symptoms: java.lang.UnsatisfiedLinkError: ... couldn't find "libscanning.so" at start-up or on the first SDK call.

Likely cause: The APK that reached the device does not contain the engine for its architecture — usually an abiFilters or splits configuration that excludes the device’s ABI, or a universal APK built with every ABI stripped.

Fix: The SDK ships armeabi-v7a, arm64-v8a, x86, and x86_64. Make sure your packaging keeps the ABIs your users run — see Application size and packaging for the recommended App Bundle and splits setup. Check what actually landed in the artifact with Android Studio’s APK Analyzer (the lib/ folder).

The First Processed Image Crashes an Emulator

Symptoms: On an arm64 emulator (the default on Apple-Silicon Macs), the app dies with an illegal-instruction error (SIGILL) the first time an image is processed. Real devices are unaffected.

Likely cause: SDK versions before 3.2.0 trusted a processor capability the emulator falsely advertises.

Fix: Update to SDK 3.2.0 or later, where emulators work end to end. There is no workaround for older versions on arm64 emulators — test those on a physical device.

Every Output Image Carries a Watermark

Symptoms: Scanning works, but processed pages have a watermark across them.

Likely cause: The SDK is running unlicensed: the license key is missing, malformed, not found where load() expects it, or bound to a different application ID — the demo application’s key, for example, licenses only the demo application. A subtler variant: an SDK object created before ScanningSdkLibrary.load() stays bound to the unlicensed state for its whole life, even after a valid key loads — nothing throws when this happens.

Fix: Check the key setup against Get started, and make sure load() runs in Application.onCreate() before anything constructs an SDK object. For evaluating in your own application without watermarks, request a free trial key bound to your application ID.

The Camera Screen Says “Camera is not available”

Symptoms: The Smart Camera opens but shows “Camera is not available” in its console and captures nothing.

Likely cause: The device (or emulator configuration) has no usable back camera, or camera initialization failed.

Fix: On emulators, set the AVD’s back camera to a webcam or the emulated scene. On devices, this state is the screen’s controlled failure mode: it ignores capture input and returns the standard cancelled result when the user leaves — your result callback receives an empty list, and no special handling is needed. See Smart Camera.

OCR Language Downloads Fail

Symptoms: Languages in the language manager show “download failed”, “server error”, or “downloads unavailable on this device”.

Likely cause: The language server URL your application configured is unreachable or returns an error page; the device is out of storage; or, on devices without a usable network stack provider, the downloader’s fallback also failed.

Fix: The row’s warning icon opens the technical error details. Check that the server URL passed to requestServer() serves the language files (see Get started — production apps must host the files themselves), and that storage is not full. A failed download never corrupts the installed languages: the previous catalogue and files stay usable.

Contacting Support

If a problem survives this page, write to support with:

1. The exact SDK build — the string from ScanningSdkLibrary.versionInfo (see Get started).
2. Device model and Android version (or emulator image), and whether a physical device reproduces it.
3. Steps that reproduce the problem, and whether it happens every time.
4. The relevant adb logcat output around the failure.

That set usually makes one round trip enough.