Ground truth:
CometChatUIKitSwift5.1.22 +CometChatSDK4.1.7 (symbols verified vscatalogs/ios-v5.json); signatures FETCHED viacometchat-ios-core/references/docs-map.md; the invariants below (init→login order, credentials flow, SPM-only) areRULES.md+cometchat-ios-core. This diagnostics catalog is cross-checked against the live{DOCS_BASE}/ui-kit/ios/troubleshooting.mdpage (base + paths incometchat-ios-core/references/docs-map.md), and adds the host-side/runtime symptoms it doesn't cover.
Companion skills (read first)
cometchat-ios-core— the correct init→login→render order, theSecrets.xcconfig→Info.plist→Bundle.maincredential flow, and the SwiftUI launch hook the fixes below restore.
Use this skill when
An iOS CometChat integration compiles but misbehaves at runtime: a screen that never fills, login that does nothing, or empty data.
Start here — iOS fails SILENTLY, on ORDER and CREDENTIALS
The two dominant causes of "the screen never populates":
login()was called beforeinitFromSettingsresolved. Both are async and must COMPLETE in order; login-before-init fails with no crash and no visible error — just a screen that never loads (cometchat-ios-core).- Credentials came through as the literal
$(COMETCHAT_APP_ID). TheSecrets.xcconfig→ attach-to-configs → declare-in-Info.plist → read-via-Bundle.mainchain has four steps; miss one and you init with the literal placeholder, which then fails auth.
Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
| Screen never populates, no error | login before init resolved | Chain them: call login only inside the init completion (cometchat-ios-core references/swiftui.md) |
| Auth fails immediately | Wrong Region, or creds read as $(...) | Region must match the dashboard app; verify Bundle.main returns the value, not the literal $( |
Values are the literal $(...) | xcconfig not attached, or Info.plist key missing | Attach Secrets.xcconfig to the build configs AND declare each key in Info.plist (references/setup-credentials.md §2-§3) |
| SPM won't resolve / kit crashes at runtime | CometChatSDK version drifted from the kit's exact pin | Pin CometChatUIKitSwift 5.1.22 + CometChatSDK 4.1.7 + CometChatCallsSDK 5.0.3 exactly (cometchat-ios-core Install) |
| Build fails after adding a Podfile | Tried CocoaPods | SPM only — a Podfile is a detection signal, not an instruction; remove the pod integration |
| Conversations empty | New app has no conversations, or wrong scope | Send a first message; check the request scope |
login "user not found" | UID does not exist in the app | Use a real UID (Dashboard → Users; fresh apps seed cometchat-uid-1) — never a guessed superhero* |
| Calls fail / no permission prompt | Missing usage-description strings or VoIP entitlement | Add NSCameraUsageDescription + NSMicrophoneUsageDescription; enable the VoIP entitlement (cometchat-ios-push/-calls) |
| Works in dev, fails in release | Auth Key stripped for release but still using login(uid:) | Switch to login(authToken:) with a server token (cometchat-ios-production) |
When the table does not cover it
Enable SDK logging and read the Xcode console: an init/lifecycle error (a call made before init() resolved) is the usual "nothing renders" cause; auth errors are almost always Region or a literal-placeholder credential. Then fetch the feature's page via cometchat-ios-core/references/docs-map.md. Never diagnose from the binary framework's headers or from memory — fetch the documented signature.
Verify it works
init and login both resolve (in order) before the chat screen renders · Bundle.main returns real credential values, not $(...) · the exact kit/SDK versions are pinned · conversations render or show the empty state · a message sends and arrives · calls prompt for permission.
What NOT to do
Do not hard-code credentials to get past the $(...) literal — fix the xcconfig/Info.plist chain; do not add CocoaPods to work around an SPM resolve issue — pin the exact versions; do not hard-code a UID to dodge "user not found."