# 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](https://developer.incode.com/docs/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](https://developer.incode.com/docs/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](https://developer.incode.com/docs/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](https://developer.incode.com/docs/ios-customization#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.