Ground truth:
@cometchat/chat-uikit-angular@5(5.1.0–5.2.0 verified). Symptoms map to causes verified against the installed kit and the live{DOCS_BASE}/ui-kit/angular/troubleshooting.mdpage (base + paths incometchat-angular-v5-core/references/docs-map.md). EveryCometChat*symbol named here exists in theangular-v5catalog; a fix that requires a symbol not in the catalog is a bug in this file, not a missing export.
Companion skills (read first)
cometchat-angular-v5-core—references/anti-patterns.mdandreferences/troubleshooting.mdcarry the same table in more depth.
Use this skill when
Something is wrong and the error message is unhelpful or absent.
Start here — Angular fails SILENTLY
Four of the five most common CometChat-Angular faults produce no error at all. Do not wait for a stack trace.
Run these four checks in order before anything else:
1. Is the component in imports: []?
Missing → Angular treats <cometchat-conversations> as unknown HTML and renders nothing. No error, no warning, blank space. This is the single most common cause.
2. Does the container have height?
csshtml, body { height: 100%; margin: 0; }
Plus a 100dvh shell and min-height: 0 on every flex column. An unsized ancestor collapses the list to 0px — markup correct, nothing visible.
3. Did login() resolve before render?
Lists render empty with no error when there is no session. Check CometChatUIKit.getLoggedInUser() is non-null at the moment the component mounts.
4. Is the binding name real?
(ccConversationClicked) never fires — the real output is (itemClick). Angular does not warn about unknown outputs. Verified names are in cometchat-angular-v5-components.
Symptom → cause → fix
| Symptom | Cause | Fix |
|---|---|---|
| Icons missing/blank across the kit | assets not registered in angular.json | add the src/lib/assets glob → output: assets; the most commonly missed step |
| Scrolling the list scrolls the WHOLE page | shell/columns missing overflow: hidden | min-height: 0 lets it shrink; overflow: hidden keeps the scroll inside the pane — both are required |
| List doesn't scroll at all — bottom items unreachable | <cometchat-conversations>/-users/-groups/-call-logs/-search/-message-list has no flex: 1; min-height: 0 of its OWN | add the .cc-fill class to the tag itself, not just its ancestors — the list resolves an internal height: 100% and does not size itself |
| Whole surface runs past the viewport / clipped, on a routed page only | <cometchat-error-boundary> is the template root and ships no :host sizing, so a height: 100% shell under it resolves against nothing | add cometchat-error-boundary { display: flex; flex-direction: column; flex: 1; min-height: 0; overflow: hidden; } — it is styled by ELEMENT, not by a class. Symptom hides when the shell uses 100dvh (viewport-relative), appears the moment it becomes 100% under a routed outlet |
<cometchat-call-logs> shows "OOPS! Looks like something went wrong" | KIT BUG (5.1.0), not your code: CallLogsService builds new CometChatUIKitCalls.CallLogRequestBuilder() without awaiting the lazy calls-SDK load, so the accessor is still null. Zero network requests are made — it fails before fetching, and Retry does not recover | No host-side fix. Do not hand-roll around it; report it. Note (error) will NOT surface it — call-logs has no error output (it takes an onError INPUT) |
| Blank space where chat should be | component not in imports: [] | add the class to that component's imports |
| Blank pane, markup correct | ancestor has no height | html, body { height: 100% } + 100dvh + min-height: 0 |
| Lists render but always empty | rendered before login() resolved | init → login before bootstrap, or gate the route |
| Click handler never fires | wrong output name | use the verified name; there is no cc prefix |
| Selected row never highlights | activeConversation not bound | bind it to the same state as the message pane |
| Messages arrive, UI does not update | async SDK callback doesn't repaint (Angular 21 is zoneless by default, so NgZone.run() won't help) | write to a signal or call ChangeDetectorRef.markForCheck() after the update (core lifecycle.md) |
| Memory grows per route change | no teardown | takeUntil(destroy$) + removeMessageListener(id) in ngOnDestroy |
| Duplicate messages after navigating | listener registered twice, never removed | register with a stable id; remove on destroy |
| "Please wait until the previous login request ends." | concurrent login() | cache the in-flight promise |
npm install fails ERESOLVE | project on Angular 22 | peer range is <22.0.0; use @angular/cli@21 |
| Build error: path not exported by package | @import of the kit stylesheet | register the full node_modules/... path in angular.json |
| Config empty at runtime | credentials in .env | Angular reads environment.ts, not .env |
| Import will not compile | bare class name used | use the exported …Component form |
| Header shows one chat, messages another | [user]/[group] mismatch | pass the same subject to header, list and composer |
| Reply button does nothing | no thread surface rendered | wire a thread panel or hide the affordance |
| Feature missing, no error | dashboard extension off | enable it for the app the credentials point at |
| Call buttons render as empty zero-size elements | uiKit.callsSDK missing from initFromSettings | add uiKit: { callsSDK: {} }; installing the package does not enable calling. Check CometChatUIKit.isCallingEnabled() |
| Lists show "OOPS!" on first load and Retry does nothing | first fetch raced login; ConversationsService caches the failure | bootstrap AFTER login resolves; give the user a retry that remounts the component |
| Calls never ring | listener not at app root, or calls SDK absent | mount <cometchat-incoming-call> at root; install the calls SDK |
| Calls fail on a LAN IP | getUserMedia needs a secure context | use HTTPS or localhost |
window is not defined | SSR running browser code | guard with isPlatformBrowser |
| Dropdown clipped | ancestor overflow: hidden or transform | remove it from the chain |
| Layout jumps when data loads | box sizes to content | pin the height so loading and loaded share one box |
Where the docs contradict this skill
One entry above still disagrees with {DOCS_BASE}/ui-kit/angular/overview.md, and this skill is right because it is verified against the published package:
- Angular 22 — the docs list it as supported; the peer range excludes it and
npm installhard-fails. Do not follow the docs here, and never--forcepast it.
Also verify against the installed package:
@cometchat/cards-angular— required since 5.1.0. (The overview's peer list now lists it — corrected upstream, verified against cometchat/docs, 2026-09-09.)
If a fix in this table seems to contradict a guide, check the installed package before changing course.
When the table does not cover it
- Confirm the symbol is real. The exported class name, not the docs title.
- Fetch the component's docs page (
core/references/docs-map.md) and compare every input you pass. - Check the browser console for a CometChat error code before assuming it is a UI problem.
- Raise the log level:
CometChatUIKit.setLogLevel(...). - Reduce to the golden path from
core. If that works, the fault is in your composition; if it does not, it is setup.
Verify it works
A fix is done when the symptom is gone and you can say which of the four silent-failure causes it was. If you cannot name the cause, the fix is a coincidence and it will come back.
Re-check after any fix: chat renders with real data · clicking a conversation opens it · sending a message appears immediately · a second browser receives it live · no console errors · nothing collapsed to zero height.
What NOT to do
- Do not
--forceor--legacy-peer-depspast anERESOLVE— you install an untested combination and the failure moves somewhere harder to find. - Do not add
!importantto fight the kit's styles — a token is not applying because the stylesheet is not registered. - Do not rebuild a component by hand because an affordance looks broken. It is nearly always a missing input or an unsized container.
