Cometchat Angular Troubleshooting

Purpose

Teaches Claude how to diagnose and fix CometChat Angular UI Kit v4 integration failures. Covers every category of failure across NgModule and standalone component setups, with an up-front triage flow so Claude asks the right questions before assuming a fix.

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

Ground truth: docs/ui-kit/angular/troubleshooting, docs/ui-kit/angular/getting-started, and first-hand failure modes from real integrations.

1. Triage — read project state before guessing

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

1a. Is CUSTOM_ELEMENTS_SCHEMA in every module that uses <cometchat-*> tags?

grep -r "CUSTOM_ELEMENTS_SCHEMA" src/

If missing from any module or standalone component that uses <cometchat-*> tags, Angular throws "Unknown element" errors. Every module/component needs it independently.

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:

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

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

grep -n "CometChatUIKit.init\|isReady\|APP_INITIALIZER" src/app/app.component.ts

Look for the init promise + isReady flag or APP_INITIALIZER. Components rendered before init completes produce blank output.

1d. Is UIKitSettingsBuilder used (not a flat object)?

grep -n "UIKitSettingsBuilder\|CometChatUIKit.init" src/

Angular requires UIKitSettingsBuilder from @cometchat/uikit-shared. A flat object passed to init() fails silently or throws a type error.

1e. Are CometChat components imported in the module?

grep -n "CometChatConversations\|CometChatMessages\|CometChatMessageList" src/app/app.module.ts

Every <cometchat-*> component must be imported in the module (or standalone component) where it's used.

1f. Is BrowserAnimationsModule imported?

grep "BrowserAnimationsModule" src/app/app.module.ts

Missing BrowserAnimationsModule causes runtime errors in components that use Angular animations.

2. Symptom → fix lookup tables

2a. Initialization + login

2b. Module / schema errors

2c. Assets / icons

2d. Layout / height issues

2e. Angular Router integration

2f. Theming

2g. Components

2h. Calling

2i. Extensions

2j. Production / auth tokens

2k. SSR / Angular Universal

3. Deep dives on common failures

3a. "The most common 'why is my chat blank' bug"

CometChat components fill 100% of their parent's height. If the parent has no bounded height, the components render at 0px and look empty.

Diagnostic:

# Check the parent container of the CometChat component
grep -B5 "cometchat-message-list\|cometchat-conversations" src/app/**/*.html

Look for the component's parent. One of these must be true:

• Parent has height: 100vh or height: 100%
• Parent is a flex column with the component getting flex: 1
• Parent has an explicit height: Npx

Broken example:

<!-- ✗ WRONG — div has no height -->
<div>
  <cometchat-message-list [user]="selectedUser"></cometchat-message-list>
</div>

Fixed:

<!-- ✓ RIGHT -->
<div style="height: 100vh; display: flex; flex-direction: column;">
  <cometchat-message-list
    [user]="selectedUser"
    style="flex: 1; overflow: hidden;"
  ></cometchat-message-list>
</div>

3b. "Unknown element" errors for <cometchat-*> tags

Two separate fixes are both required:

1. Import the component in the module's imports array:

   import { CometChatConversations } from "@cometchat/chat-uikit-angular";
   @NgModule({ imports: [CometChatConversations] })
   

2. Add CUSTOM_ELEMENTS_SCHEMA to the module's schemas:

   import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
   @NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })
   

Both are required. Missing either one produces the "Unknown element" error.

3c. Components render before init completes

The most reliable fix is APP_INITIALIZER (see cometchat-angular-patterns § 1). If not using APP_INITIALIZER, use *ngIf="isReady":

// app.component.ts
isReady = false;

ngOnInit(): void {
  CometChatUIKit.init(settings)
    .then(() => CometChatUIKit.getLoggedinUser())
    .then((user) => user || CometChatUIKit.login({ uid: "cometchat-uid-1" }))
    .then(() => (this.isReady = true))
    .catch(console.error);
}

<!-- app.component.html -->
<ng-container *ngIf="isReady">
  <router-outlet></router-outlet>
</ng-container>

4. v3 → v4 upgrade gotchas

If the user is upgrading from @cometchat/chat-uikit-angular@3, these are the common breakages.

Upgrade sequence

# 1. Update the main kit
npm install @cometchat/chat-uikit-angular@latest

# 2. Update peer packages
npm install @cometchat/uikit-elements@latest @cometchat/uikit-resources@latest @cometchat/uikit-shared@latest

# 3. Replace flat settings object with UIKitSettingsBuilder
# 4. Replace CometChatTheme class with CometChatThemeService injection
# 5. Rename onClick → onItemClick throughout templates
# 6. Add CUSTOM_ELEMENTS_SCHEMA to all modules (new requirement in v4)
# 7. Add assets config to angular.json (new requirement in v4)
# 8. Rebuild + test

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

1. Read the raw error. Angular errors are usually specific — "Can't bind to 'user'" is different from "NullInjectorError".
2. Check the browser console + Angular DevTools. Angular DevTools shows the component tree and change detection state.
3. Search the upstream docs MCP (cometchat-docs if installed).
4. If the issue is a kit bug, file at https://github.com/cometchat/cometchat-uikit-angular/issues with a minimal repro.

6. Hard rules (diagnostic best-practice)

1. Don't assume — triage first. § 1 gets the schema, assets, init state, and module imports before proposing a fix.
2. Don't suggest "try reinstalling node_modules" as a first step. Check the schema, assets config, and module imports first.
3. When recommending a rebuild, say why + what to rebuild. "ng build after adding assets config" is more useful than "try rebuilding."
4. Never guess a fix that requires code changes without first gathering facts.

Skill routing reference