This document lists known issues, their status, and workarounds.

| #  | Issue                                                                                               | Status                        | Platform       |
|----|-----------------------------------------------------------------------------------------------------|-------------------------------|----------------|
| 1  | [Virtual environment crash on Android](https://developer.incode.com/docs/cordova-known-issues#2-virtual-environment-crash-on-android) | Expected behavior (by design) | Android        |
| 2  | [Emulator/simulator false security triggers](https://developer.incode.com/docs/cordova-known-issues#3-emulatorsimulator-false-security-triggers) | Workaround available          | All            |
| 3  | [iOS double initialization](https://developer.incode.com/docs/cordova-known-issues#4-ios-double-initialization) | By design                    | iOS            |
| 4  | [iOS-only jailbreak detection](https://developer.incode.com/docs/cordova-known-issues#5-ios-only-jailbreak-detection) | By design                    | iOS / Android  |
| 5  | [setCommonConfig deprecated](https://developer.incode.com/docs/cordova-known-issues#6-setcommonconfig-deprecated) | Deprecated                   | All            |

## 1\. Virtual environment crash on Android

**Status:** Expected behavior (security feature, by design).

**Description:** When running in a virtual / emulated environment, the app may crash with a `NullPointerException` originating in `ThemeConfiguration$Builder` (and related repository classes). This is triggered by hook and virtual-environment detection, which intentionally cause a native crash that cannot be caught or handled by application code. Example stack traces:

```undefined
java.lang.NullPointerException
    at com.incode.welcome_sdk.ThemeConfiguration$Builder.setLabelSmallStyle(SourceFile:1066)
    at com.incode.welcome_sdk.f.c(SourceFile:150)
    at com.incode.welcome_sdk.data.local.m.as(SourceFile:22)
    at com.incode.welcome_sdk.IncodeWelcome.startOnboardingSection(SourceFile:18)
```

```undefined
java.lang.NullPointerException: Attempt to get length of null array
    at com.incode.welcome_sdk.data.IncodeWelcomeRepository.d(SourceFile:320)
    at com.incode.welcome_sdk.data.IncodeWelcomeRepository.i(SourceFile:214)
```

**Workaround:** Do not run production builds in virtual environments. For development/testing on emulators, see issue 3. Note that, as of 4.2.0, emulator and root detection no longer abort the flow — the onboarding continues normally — but **hook and virtual-environment detection still trigger an unrecoverable native crash**.

## 2\. Emulator/simulator false security triggers

**Status:** Workaround available.

**Description:** Running on simulators/emulators can trigger security checks that return errors such as `simulatorDetected`.

**Workaround:** Set `testMode` to `"true"` when calling [`initializeSDK`](https://developer.incode.com/docs/cordova-api-reference#initializesdk) on simulators/emulators. Use `testMode: "false"` on real devices in production (otherwise you may receive a `testModeEnabled` error).

## 3\. iOS double initialization

**Status:** By design.

**Description:** The iOS SDK guards against double initialization. Calling `initializeSDK` more than once per app lifecycle is a no-op on iOS.

**Workaround:** Initialize once per app lifecycle. Use [`isInitialized`](https://developer.incode.com/docs/cordova-api-reference#isinitialized) to check state before re-initializing.

## 4\. iOS-only jailbreak detection

**Status:** By design.

**Description:** Jailbreak detection is an iOS-only feature. The `disableJailbreakDetection` parameter of `initializeSDK` has **no effect on Android**.

**Workaround:** None needed — set `disableJailbreakDetection` only when targeting iOS behavior.

## 5\. setCommonConfig deprecated

**Status:** Deprecated since 4.6.0; scheduled for removal.

**Description:** `setCommonConfig` is deprecated. It now internally forwards to [`showCloseButton`](https://developer.incode.com/docs/cordova-api-reference#showclosebutton) and logs a deprecation warning. It will be removed in a future major release.

**Workaround:** Use `showCloseButton(successCallback, errorCallback, allowUserToCancel)` instead.