Document Scanner SDKTroubleshooting Pixelnetica™ Document Scanning SDK for Apple iOS
Common developer issues and how to resolve them. For product, pricing, and general questions, see the FAQ.
Installation
The package won’t resolve, or I get a checksum mismatch. SwiftPM caches binary artifacts by checksum. After an SDK update, reset the package caches (File ▸ Packages ▸ Reset Package Caches) and resolve again. Confirm the package URL and that your version rule allows the release you expect. See Installation.
After updating the SDK, the compiler can’t find a type that clearly exists. This is usually a stale module cache. Clean the build folder (Product ▸ Clean Build Folder) and rebuild.
The package resolves, but the build fails to link (“Undefined symbols”). A binary-framework link failure after resolution usually means a missing system dependency. Confirm your target links the frameworks the SDK relies on and builds for a supported slice (arm64 device, or arm64/x86_64 simulator); then clean and rebuild.
Distribution & code signing
The app builds in Debug but fails to archive, or is rejected at upload. Binary xcframeworks must be embedded with Embed & Sign so Xcode re-signs them with your identity. Confirm the SDK frameworks are set to Embed & Sign (not Do Not Embed) in your target’s Frameworks, Libraries, and Embedded Content. A launch-time “invalid code signature” crash points to the same setting.
How do I symbolicate a crash that points inside the SDK? The xcframeworks ship with bundled dSYMs. Keep the dSYM for the SDK version you shipped, and symbolicate the crash report against it as you would your own (Xcode’s Organizer, or atos/symbolicatecrash with the matching UUID).
Licensing
Results come out watermarked. No active license is applied, so the SDK is in evaluation mode. Apply a valid key — see Licensing.
PxLicense.initialize(withKey:) returns AppID_Mismatch. The key was issued for a different bundle identifier. License keys are bound to one bundle ID; request a key for the bundle ID you build with.
The key looks correct but is still rejected. License keys must be passed verbatim. A key that picked up stray whitespace, line breaks, or truncation when copied will fail validation — re-copy it intact. (Validation is fully on-device; no network is involved.)
The license was working and now reports expired. Check status and validTs on the active license. An expired license falls back to evaluation (watermarked) behaviour.
Camera
The camera screen opens and immediately closes, or fails to start. Add an NSCameraUsageDescription string to your Info.plist — iOS blocks the camera without it.
The preview is black even though permission was granted. The camera may be restricted (Screen Time / parental controls) or already in use by another app or capture session. Check AVCaptureDevice.authorizationStatus for .restricted, and make sure no other session holds the camera when you present the scanner.
Opening and closing the camera in quick succession crashes or hangs. Let the camera screen finish tearing down its capture session before presenting it again, rather than dismissing and re-presenting back-to-back.
I can’t test scanning on the Simulator. The Simulator has no camera. Use Process an existing image to exercise detection, cropping, enhancement, OCR, and export there.
OCR
OCR returns no text or an error for a language. The recognition language pack must be downloaded before first use — see OCR languages. Orientation/script detection (OSD) is bundled and needs no download.
OCR results are poor or inaccurate. Recognition quality depends on the input. Make sure the right language(s) are selected (a wrong or missing language pack produces garbled text), and feed the recogniser a cropped, de-skewed, adequately-resolved page — run OCR on the enhanced/rectified image, not a raw low-resolution photo.
Which formats and OCR require a license feature? PNG, TIFF, and PDF export and OCR are licensed features. Check the active license’s features mask — see Licensing.
Export & PDF
My searchable PDF doesn’t seem searchable. The text layer is embedded but hidden behind the page image (that is what makes it searchable rather than visible). If a viewer shows no selectable text or renders the page blank, it is usually the viewer, not the file — some lightweight or older readers don’t fully implement the modern image codecs the SDK uses (JBIG2, JPEG 2000). Open it in a fully standards-compliant viewer (Adobe Acrobat/Reader, or a current mainstream viewer). See Export ▸ Viewing the PDFs.
Performance & memory
Memory spikes or the app is terminated when scanning many pages or exporting a large PDF/TIFF. Process and release pages incrementally rather than holding every full-resolution page in memory at once, and write multi-page documents page-by-page through the open writer. Run OCR and enhancement off the main thread so a large job doesn’t block the UI.
Engine
A processing or export call throws. Core-engine calls can raise exceptions. Wrap them with PxCatchExceptions and handle the thrown NSError, as shown in Export.