# Known Issues

This page lists the known issues, limitations, and intentional constraints you are most likely to run into with the Incode iOS SDK. Each entry describes a lasting, customer-facing behavior, not a temporary bug. The [release notes](https://developer.incode.com/docs/releases-ios-sdk) track and resolve temporary bugs.

This list is a quick summary. [Migration Guide](https://developer.incode.com/docs/migration_guide) holds the authoritative, version-specific notes. Check those pages for the exact release where a behavior changed, or a limitation started or ended.

***

## NFC

- **The SDK tries the PACE protocol first, then falls back to BAC.** When opening an NFC chip, the SDK attempts Password Authenticated Connection Establishment (PACE) when the document advertises support for it, and falls back to Basic Access Control (BAC) otherwise. See [NFC](https://developer.incode.com/docs/module-nfc-scan).

***

## Capture-Only Mode

- **Forward **`metadata`** to the Incode API.** In Capture-Only mode (`IncdOnboardingManager.shared.sdkMode = .captureOnly`), the SDK returns captures to your app without uploading them, and your app is responsible for submission. When you submit a capture yourself, forward the `metadata` field from the capture result—`IdScanResult.metadata` and `SelfieScanResult.metadata`—to the Incode API. This field carries proprietary capture metadata required by the Incode backend to process the capture. See [Capture-Only Mode](https://developer.incode.com/docs/ios-capture-only-sdk).

***

## On-Device Face Processing for Selfie Scan V2

- **Constrained configuration.** On-device face results submission for the Selfie module, configured through Dashboard/Workflows, is only honored when all of the following hold:

  - End-to-end encryption is active for the session,
  - The Login variant is included in the build, and
  - The module runs with a visible UI (headless mode is not supported).

  If any of these is not met, on-device submission is not used. Note that the iOS requirements differ from the Android SDK. See [Selfie](https://developer.incode.com/docs/module-selfie).

***

## Simulator

- **Camera and NFC are unavailable on the iOS Simulator.** Camera- and NFC-dependent modules cannot produce real captures on the Simulator; the SDK gates camera and NFC availability when running there. Run capture flows on a physical device. NFC additionally requires iOS 13.0 or later and NFC-capable hardware. On unsupported OS versions the SDK reports `NFCScanError.notAvailable`.

***

## Device Environment Detection

- **Environment signals are reported, not enforced.** The iOS SDK collects device-integrity signals: jailbreak, runtime-hooking/instrumentation, and, in release builds, debugger-attach detection. It reports them to the Incode backend as upload metadata for risk analysis. These signals are **non-blocking**: they do not stop onboarding, they do not surface as a catchable error or delegate callback, and they do not crash the app. You cannot disable them, and there is no integrator hook to handle them.

<br />