cometchat-ios-troubleshooting

Ground truth: CometChatUIKitSwift 5.1.22 + CometChatSDK 4.1.7 (symbols verified vs catalogs/ios-v5.json); signatures FETCHED via cometchat-ios-core/references/docs-map.md; the invariants below (init→login order, credentials flow, SPM-only) are RULES.md + cometchat-ios-core. This diagnostics catalog is cross-checked against the live {DOCS_BASE}/ui-kit/ios/troubleshooting.md page (base + paths in cometchat-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, the Secrets.xcconfig→Info.plist→Bundle.main credential 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":

1. login() was called before initFromSettings resolved. 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).
2. Credentials came through as the literal $(COMETCHAT_APP_ID). The Secrets.xcconfig → attach-to-configs → declare-in-Info.plist → read-via-Bundle.main chain has four steps; miss one and you init with the literal placeholder, which then fails auth.