cometchat-angular-troubleshooting— agent skill

Purpose

Teaches Claude how to diagnose and fix CometChat Angular UI Kit v5 (@cometchat/chat-uikit-angular@5) integration failures. This is a symptom → cause → fix reference. v5 is standalone-component-based, Angular 17–21 — there is no NgModule and no CUSTOM_ELEMENTS_SCHEMA. If you find yourself reaching for either, you are applying a v4 mental model.

Read `cometchat-angular-core` first — most "why doesn't this work" issues trace to the init / login / standalone-import order explained there.

Ground truth: @cometchat/[email protected] bundled types (node_modules/@cometchat/chat-uikit-angular/types/cometchat-chat-uikit-angular.d.ts), docs/ui-kit/angular, and first-hand failure modes from real v5 integrations. Verify any non-obvious symbol against the installed .d.ts before relying on it. Official docs: https://www.cometchat.com/docs/ui-kit/angular/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP).

1. Triage — read project state before guessing

When the user reports a problem, gather facts before proposing a fix.

1a. Does the installed Angular version satisfy the kit's peer range?

node -e "console.log(require('@angular/core/package.json').version)"
npm ls @cometchat/chat-uikit-angular

UI Kit v5 declares @angular/core / @angular/common peers of >=17.0.0 <22.0.0. On Angular ≤16 the install warns (or errors under strict peers) and standalone-component imports fail at build time. Fix: upgrade Angular to 17–21.

1b. Are the assets configured in angular.json?

grep -A5 '"assets"' angular.json | grep cometchat

If missing, icons render as broken images. The required entry under projects.<app>.architect.build.options.assets:

{ "glob": "**/*", "input": "./node_modules/@cometchat/chat-uikit-angular/src/lib/assets", "output": "assets/" }

1c. Is init complete before any <cometchat-*> component renders?

grep -rn "CometChatUIKit.init\|APP_INITIALIZER\|isReady" src/

Look for the init Promise resolved in main.ts before bootstrapApplication(...) (the v5 canonical — see cometchat-angular-core §3 / cometchat-angular-patterns), or wired into an APP_INITIALIZER factory (the alternative), or an isReady flag set after the init+login chain resolves. Components rendered before init completes produce blank output or a "CometChat is not initialized" console error.

1d. Is UIKitSettingsBuilder used (not a flat object), imported from the right package?

grep -rn "UIKitSettingsBuilder\|CometChatUIKit.init\|uikit-shared" src/

In v5 UIKitSettingsBuilder is exported from `@cometchat/chat-uikit-angular`. If you see an import from @cometchat/uikit-shared / -elements / -resources, that's a v4 package set that does not exist in v5 — it will fail to resolve. A flat object passed to init() (instead of a built UIKitSettings) also fails.

1e. Are the CometChat component classes imported into the standalone component that renders them?

# v5 exports class names with the `Component` suffix; selectors do not carry it.
grep -rnE "CometChat(Conversations|MessageList|MessageHeader|MessageComposer|Users|Groups|GroupMembers|CallButtons|IncomingCall|OutgoingCall|OngoingCall|CallLogs)Component" src/

Every <cometchat-*> tag requires its *Component class in the host standalone component's imports: []. There is no module to register them in, and no schema.

1f. Are the peer SDKs installed at the right major?

npm ls @cometchat/chat-sdk-javascript @cometchat/calls-sdk-javascript dompurify

Chat SDK must be ^4.1, dompurify ^3 (both auto-pulled by npm 7+). Calls features additionally require @cometchat/calls-sdk-javascript@^5 — installed explicitly.

2. Symptom → cause → fix lookup tables

2a. Install / peer-dependency / version

2b. "is not a known element" / template binding errors

2c. Initialization + login

2d. Assets / icons

2e. Layout / height

2f. Change detection / NgZone

2g. Theming — CSS variables

2h. Components / bindings

2i. Calling

2j. Production / auth tokens

2k. SSR / Angular Universal

3. Deep dives on common failures

3a. "is not a known element" — the v5 standalone-import fix

v5 components are standalone Angular components (not generic web components). The fix is to import the component class into the host standalone component's imports: [] — never CUSTOM_ELEMENTS_SCHEMA:

import { Component } from "@angular/core";
import { CometChatConversationsComponent } from "@cometchat/chat-uikit-angular";

@Component({
  selector: "app-chat",
  standalone: true,
  imports: [CometChatConversationsComponent],   // ← register the class you render
  template: `<cometchat-conversations></cometchat-conversations>`,
})
export class ChatComponent {}

• The class carries the Component suffix (CometChatConversationsComponent); the selector does not (<cometchat-conversations>).
• Import only the components you actually use.
• If you add CUSTOM_ELEMENTS_SCHEMA, Angular stops complaining but the real component never instantiates — you get a blank render instead of an error. Remove it and import the class.
• On a not-yet-migrated NgModule app, standalone classes can go into @NgModule({ imports: [...] }) — still no schema.

3b. The most common "why is my chat blank" bug — inline elements + bounded height

The kit's <cometchat-*> elements are `display: inline` by default — they do not flex, fill, or scroll on their own. Two things are load-bearing: (1) the host is a flex column with a resolvable height, and (2) each custom element is itself made a flex column. A parent with no bounded height — or an element left inline — renders the list at 0px or makes it overflow instead of scroll.

grep -rB5 "cometchat-message-list\|cometchat-conversations" src/app

Broken:

<!-- ✗ div has no height; element left inline -->
<div>
  <cometchat-message-list [user]="selectedUser"></cometchat-message-list>
</div>

Fixed:

<!-- ✓ host is a flex column with height; element made a flex column with min-height: 0 -->
<div style="height: 100vh; display: flex; flex-direction: column;">
  <cometchat-message-list
    [user]="selectedUser"
    style="flex: 1; min-height: 0; overflow: hidden; display: flex; flex-direction: column;"
  ></cometchat-message-list>
</div>

• min-height: 0 is the part everyone forgets: a flex child defaults to min-height: auto, so without it the list grows past the parent and overflows the viewport instead of scrolling internally.
• The height: 100% chain needs a root — set html, body { height: 100% } in global styles, otherwise height: 100% resolves against an auto-height ancestor and collapses.
• See cometchat-angular-placement for the full sidebar / two-pane / Material-tab host contracts.

3c. Components render before init completes

Most reliable fix — resolve CometChatUIKit.init(...) in main.ts before bootstrapApplication(...) so nothing mounts until the SDK is ready (the v5 canonical — see cometchat-angular-core §3 and cometchat-angular-patterns):

// main.ts
import { bootstrapApplication } from "@angular/platform-browser";
import { UIKitSettingsBuilder, CometChatUIKit } from "@cometchat/chat-uikit-angular";
import { environment } from "./environments/environment";
import { App } from "./app/app";
import { appConfig } from "./app/app.config";

const settings = new UIKitSettingsBuilder()
  .setAppId(environment.cometchat.appId)
  .setRegion(environment.cometchat.region)
  .setAuthKey(environment.cometchat.authKey)
  .subscribePresenceForAllUsers()
  .build();

CometChatUIKit.init(settings)
  .then(() => bootstrapApplication(App, appConfig))
  .catch((err) => console.error("CometChat init failed:", err));

Alternative — block bootstrap with an APP_INITIALIZER factory that returns the init Promise (Angular waits for it before mounting):

// providers: [{ provide: APP_INITIALIZER, useFactory: () => () => CometChatUIKit.init(settings), multi: true }]

If you don't want to block bootstrap, init in AppComponent.ngOnInit() and gate the outlet:

isReady = false;

ngOnInit(): void {
  const settings = /* UIKitSettingsBuilder … .build() */;
  CometChatUIKit.init(settings)
    .then(() => CometChatUIKit.getLoggedinUser())
    .then((user) => user || CometChatUIKit.login("cometchat-uid-1"))  // bare string
    .then(() => (this.isReady = true))
    .catch(console.error);
}

<ng-container *ngIf="isReady">
  <router-outlet></router-outlet>
</ng-container>

3d. View not updating after an SDK callback (NgZone)

CometChat SDK listeners fire outside Angular's zone, so a field you mutate in a callback won't trigger change detection. Re-enter the zone (or prefer the async pipe over loggedInUser$):

import { NgZone } from "@angular/core";

constructor(private zone: NgZone) {}

// inside an SDK listener callback:
this.zone.run(() => {
  this.latestMessage = message;   // now change detection runs
});

Idiomatic alternative — bind the observable directly so Angular owns the subscription:

<span *ngIf="uiKit.loggedInUser$ | async as user">{{ user.getName() }}</span>

3e. ng build warns "Module '@cometchat/chat-sdk-javascript' … is not ESM" — benign

A successful ng build emits a CommonJS-interop optimization-bailout WARNING for @cometchat/chat-sdk-javascript (the chat SDK is published as CommonJS, not ESM). This is harmless — the build still exits 0 and the kit works. Do NOT try to "fix" it by switching SDK imports around. If you want to silence it, add the package to angular.json → architect.build.options.allowedCommonJsDependencies:

"allowedCommonJsDependencies": ["@cometchat/chat-sdk-javascript"]

(Verified 2026-06-14: fresh Angular 21 + @cometchat/[email protected] build succeeds with only this warning.)

4. Escalation — when the above doesn't solve it

1. Read the raw error. "is not a known element" (missing standalone import) is a different problem from "NullInjectorError" (DI) or "window is not defined" (SSR).
2. Check the browser console + Angular DevTools. DevTools shows the component tree and change-detection state — useful for the NgZone class of bugs.
3. Confirm versions: Angular 17–21, @cometchat/chat-uikit-angular@^5, @cometchat/chat-sdk-javascript@^4.1, and @cometchat/calls-sdk-javascript@^5 for calls.
4. Search the upstream docs MCP (cometchat-docs if installed) for prop/event/error meanings.
5. If it's a kit bug, file at https://github.com/cometchat/cometchat-uikit-angular/issues with a minimal standalone-component repro.

5. Hard rules (diagnostic best-practice)

1. Triage first (§1): Angular version, assets config, init/render order, standalone imports, peer SDKs — before proposing a fix.
2. Never suggest `CUSTOM_ELEMENTS_SCHEMA` for an unknown <cometchat-*> element — the v5 fix is importing the *Component class into imports: [].
3. Never suggest `CometChatThemeService`, `CometChatUIKitLoginListener`, `login({ uid })`, or `@cometchat/uikit-shared` — all are v4 and absent in v5.
4. Don't lead with "reinstall node_modules." Check version/peers, assets, init order, and imports first.
5. When recommending a rebuild/restart, say what and why — e.g. "restart ng serve after editing angular.json (read at startup)."
6. Don't propose code changes before gathering facts.

Skill routing reference