AGENT SKILL

cometchat-ios-troubleshooting

Diagnose a broken CometChat iOS (Swift) integration — a screen that never populates, credentials read as the literal $(...), login that silently fails, empty lists, no messages, or a version/SDK mismatch. Triggers: 'cometchat ios not working', 'chat screen blank swift', 'cometchat login not working ios', 'credentials not read swift', 'conversations empty ios', 'cometchat swift errors'.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
cometchat-ios-troubleshooting
license
MIT
metadata
{ "tags": "cometchat ios swift troubleshooting debug diagnostics blank-screen spm", "author": "CometChat", "version": "1.0.0" }
description
Diagnose a broken CometChat iOS (Swift) integration — a screen that never populates, credentials read as the literal $(...), login that silently fails, empty lists, no messages, or a version/SDK mismatch. Triggers: 'cometchat ios not working', 'chat screen blank swift', 'cometchat login not working ios', 'credentials not read swift', 'conversations empty ios', 'cometchat swift errors'.
compatibility
CometChatUIKitSwift 5.2.3+ (resolves CometChatSDK 4.1.10+); Xcode 16+; iOS 15.1+; SPM only

03 SKILL.md 正文

Ground truth: CometChatUIKitSwift 5.2.3 + CometChatSDK 4.1.10 (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.

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 / app crashes at launch with Library not loaded: @rpath/CometChatCallsSDK.framework a hand-added exact CometChatSDK pin fights the kit's own from: "4.1.10", or the kit is 5.2.0 to 5.2.2 (launch crash without the Calls SDK) Depend on CometChatUIKitSwift alone, Up to Next Major from 5.2.3; remove the Chat SDK pin (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."

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k