# troubleshooting — CometChat Android v6: symptom → cause → fix

> Ground truth: `ui-kit/android/troubleshooting.md` (docs rows) + `getting-started-*` Warnings + installed 6.0.5 `CometChatUIKit.kt` error codes, verified 2026-08-20.

The fast symptom-table for a broken integration. Each row is a REAL failure mode — fix in the app; don't fetch docs for these. Deeper detail is cross-linked to the sibling reference. For anything not here → the docs page `{DOCS_BASE}/ui-kit/android/troubleshooting.md` (`docs-map.md`).

## The table
| Symptom (what the user sees) | Root cause | Fix |
|---|---|---|
| **Build fails: `Could not find com.cometchat:chatuikit-...`** | The CometChat Maven repository is missing — the kit isn't on mavenCentral | Add `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to `settings.gradle(.kts)` `dependencyResolutionManagement.repositories`, then re-sync. |
| **`Duplicate class android.support.v4.*` — on a CLEAN, single-cohort app** | NOT a version conflict. `com.cometchat:chat-sdk-android` still pulls a pre-AndroidX transitive: `android.arch.lifecycle:extensions:1.1.1` → `com.android.support:support-compat:26.1.0`, which collides with `androidx.core:core`. | Set BOTH in `gradle.properties`: `android.useAndroidX=true` and `android.enableJetifier=true`. Verified on a clean app 2026-08-24 (removing the line reproduces the failure). The review harness carries the same pair. |
| **`Duplicate class org.jetbrains.annotations.*` at dexing** | `io.noties:prism4j` pulls `annotations-java5:17`, colliding with `annotations:23` from AndroidX/Kotlin | `configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") }` — see core's install block. |
| **`Dependency 'androidx.core:core:1.18.0' requires Android Gradle plugin 8.9.1 or higher`** | AGP floor understated as 8.9 | AGP **8.9.1**. |
| **`kotlin-stdlib … metadata is 2.2.0, expected version is 2.0.0` / `Internal compiler error`** | Kotlin floor understated as 2.0 | Kotlin **2.1+** (2.0.21 fails; the review harness builds on 2.1.20). |
| **Duplicate class / resource merge errors; or two kit majors in the tree** | version_conflict — both cohort artifacts installed, or a v5 `chat-uikit-android` alongside v6 `chatuikit-*` | STOP and reconcile: keep ONE cohort (`chatuikit-kotlin-android` OR `chatuikit-compose-android`) and ONE major; v5→v6 goes through `upgrading-from-v5`. See `setup-credentials.md` §3. |
| **Init `onError` / `init()` fails silently** | Wrong App ID or Region (or empty values written to the settings JSON) | Re-check Dashboard → Credentials; Region must match (`us`/`eu`/`in`) — an auth error on init is most commonly a Region mismatch. See `setup-credentials.md` §6. |
| **Init `onError: ERR_SETTINGS_FILE_NOT_FOUND`** | `app/src/main/assets/cometchat-settings.json` is missing (it's gitignored — fresh clones don't have it) | Re-create the settings JSON from the dashboard creds (`setup-credentials.md` §4/§5). |
| **Init `onError: ERR_SETTINGS_INVALID`** | `appId` or `region` missing/empty in `cometchat-settings.json` | Fill both required root keys; they are not secrets and must always be present. |
| **Login `onError: ERR_UID_NOT_FOUND` / "UID not found"** | The UID doesn't exist in this CometChat app (hardcoded/guessed sample) | Use a UID that EXISTS: Dashboard → Users (fresh apps seed `cometchat-uid-1…5`), create one there, or `CometChatUIKit.createUser` (dev). See `setup-credentials.md` §7. |
| **Login does nothing — no success, no error** | `login()` called before `init()` resolved — the docs Warning: it "will fail silently" | Call `login` only inside init's `onSuccess`; the init→login→render order is invariant. See `lifecycle.md`. |
| **Blank / stuck splash or gate screen** | The gate never unlocks: an `onError` was swallowed (wrong Region, missing settings file, bad UID), so neither navigation nor an error message fires | Surface every `onError` (`e.message`) on the gate UI; check logcat for the CometChatException. See `lifecycle.md` "Surfacing CometChatException". |
| **Blank screen after login / component stuck on loading** | A `CometChat*` component rendered before init+login resolved, or (message screen) no `User`/`Group` was set on it | Gate rendering on both callbacks; pass the selected `conversationWith` entity to header/list/composer — the list shows only its loading indicator without one (docs Warning). See `component-props.md`. |
| **Conversations list renders but is EMPTY** | Fresh app with no conversations yet — or credentials point at a different app than expected | Seed data: log in as another seeded user (`cometchat-uid-2`) on a second device/emulator and send a message; or verify the App ID matches the dashboard app you're looking at. An `onEmpty` fire with valid creds is data, not a bug. |
| **Composer hidden under the keyboard** | Window doesn't resize for the IME | Views: `android:windowSoftInputMode="adjustResize"` on the chat Activity; Compose: `imePadding()` on the message column. See `layout.md` invariant 3. |
| **Header/composer under the status/nav bars** | `enableEdgeToEdge()` without inset handling | `Scaffold(contentWindowInsets = WindowInsets.statusBars)` + `navigationBarsPadding()` (Compose) / inset padding on the root (Views). See `layout.md` invariant 2. |
| **Chat surface is a ~0dp sliver or grows into place** | `wrap_content`/unbounded height on a list-shaped component | `match_parent`/`fillMaxSize()`; message list `0dp`+`layout_weight="1"` / `weight(1f)`. See `layout.md` invariants 1/5. |
| **Messages don't arrive in real time** (only on refresh/reopen) | Your own SDK listener never registered or removed too early (drop-ins manage their own) — or no network connection so the socket is down | Register `CometChat.addMessageListener(listenerId, ...)` in the screen's active lifecycle and remove it in the matching teardown — not before; verify connectivity (the SDK reconnects automatically). See `anti-patterns.md` #6. |
| **Tapping "Reply in thread" does nothing** | `onThreadRepliesClick` not wired (navigation is the host's job) | Wire it to a thread screen (`CometChatThreadHeader` + parent-scoped list + composer via `parentMessageId`), or hide the option. See `component-props.md`. |
| **Network/"cleartext" errors; init callback never fires** | `android.permission.INTERNET` missing from the manifest (or network blocked) | Add `<uses-permission android:name="android.permission.INTERNET" />` (+ `ACCESS_NETWORK_STATE`) to `AndroidManifest.xml` — the docs guide requires both; then re-check Region. |
| **`setOnItemClick` not firing** | Selection mode set to `MULTIPLE` consumes item clicks | Set selection mode `NONE` for standard click behavior (docs troubleshooting row). |
| **Release build crashes / kit classes missing** | R8/ProGuard stripped CometChat classes | Add `-keep class com.cometchat.** { *; }` to `proguard-rules.pro` (docs troubleshooting row). |

## When it's NOT in the table
- **Any param/signature question** → fetch the component's `.md` twin via `docs-map.md`; never answer from memory.
- **A feature renders empty** (stickers/polls/AI) → the extension likely isn't enabled in the Dashboard (see `cometchat-android-v6-features`).
- **Still stuck** → logcat first: a `CometChatException` code beats guessing (4xx = auth/plan/config, not a code bug); confirm the settings JSON values, the cohort artifact, and that the docs' `minSdk`/`jvmTarget` prerequisites hold; then the docs troubleshooting page for the long tail (theming, calling, localization, sound).