Troubleshooting

This page lists common iOS SDK integration issues and how to resolve them.

The App Crashes or a Feature "Isn't Included"

Cause: You're calling an API for a feature that isn't compiled into your variant. For example, startFaceLogin needs the -l variant, NFC needs -nfc, video conference needs -vc.

Fix: Switch to a variant that includes the feature.

The Camera/Microphone Permission Prompt Never Appears, or the Flow Fails Immediately

Cause: A required Info.plist usage-description key is missing.

Fix: Add the keys for the modules you use; see Add Required Permissions. Missing keys also cause App Store rejection.

onError Reports permissionsDenied

Cause: The user declined camera, microphone, or location access.

Fix: Detect the case and route the user to Settings to re-enable it.

Nothing Is Presented After I Start a Flow

Cause: IncdOnboardingManager.shared.presentingViewController was not set before starting the flow. Without it, UI flows fail with presentingViewControllerNotSet.

Fix: Set presentingViewController to a visible view controller before starting the flow.

Initialization Behaves Differently on a Real Device and the Simulator

Cause: IncdInitError.simulatorDetected is returned on simulators for certain configurations, and testModeEnabled when testMode: true.

Fix: Verify url, apiKey, and that testMode is set as intended.

IncdError.jailbreakDetected

Cause: The device failed the SDK's integrity check via isSDKEntierlyInitialized (the "Entierly" spelling is the real, shipping property name), which returns flag == false with error set to IncdError.integrityCompromised. This is expected on jailbroken or otherwise tampered devices.

Fix: This check cannot be disabled; the disableJailbreakDetection flag was removed as of SDK 5.45.0. If you need to test on a jailbroken/tampered device, use a clean device or simulator instead.

IncdError.resourcesNotFound

Cause: ML resources aren't available.

Fix: If you use the static variant with On-Demand Resources, download them first. See Manage On-Demand Resources.

IncdFlowError.sectionAlreadyRunning

Cause: You started a new section while one was still active.

Fix: Wait for the current section to finish before calling startOnboardingSection again.

Network/TLS Failures After Enabling Pinning

Cause: IncdError.sslPinningFailed indicates the server certificate didn't match.

Fix: Re-check configureSSLPinning(enabled:forced:) and your network environment. Proxies break pinning.

ID/Selfie Capture Keeps Failing Quality Checks

Cause: Inspect the result objects: IdScanResult.scanStatus (errorGlare, errorSharpness, errorReadability, wrongSide) and SelfieScanResult.error (spoofDetected, faceMaskDetected, lensesDetected, tooDark).

Fix: Show guidance to the user and consider the relevant tutorial and retake options.

Strings Are Wrong or in the Wrong Language

Cause: Runtime language or string customization isn't configured as expected.

Fix: See Localize Display Text for runtime language override and string customization.

If you need support, contact your Incode account representative or the support channel provided to your organization. When reporting an integration issue, include:

• SDK version and variant (IncdOnboardingManager.version; for example: 5.31.0-d-l).
• iOS version and device model.
• The module/step where it occurs and the exact error case (IncdInitError/IncdFlowError/IncdError) and its description.
• Whether you're using a Dashboard Flow/Workflow or a code-defined flow.
• The SDKMode.
• Relevant SDK logs (enable with loggingEnabled: true at init).

Avoid sharing API keys, session tokens, or any end-user PII in bug reports.