---
title: "Troubleshooting"
url: "https://developer.incode.com/sdk-reference/ios-troubleshooting/"
section: "sdk-reference"
group: "iOS SDK / iOS Getting Started"
version: "v1.1"
status: "live"
---
# Troubleshooting

This page lists common iOS SDK integration issues and how to resolve them. If you need additional support, contact your Incode account representative or the support channel provided to your organization. When reporting an integration issue, include:

- SDK version, from `IncdOnboardingManager.version` (for example: `5.50.0`), and the variant you installed (for example: `-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.

## 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](/sdk-reference/ios-sdk/#distribution-and-variants). 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](/sdk-reference/setup-ios/#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](/sdk-reference/setup-ios/#manage-on-demand-resources-odr).


## 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](/sdk-reference/ios-customization/#localize-display-text) for runtime language override and string customization.