Cometchat Troubleshooting

Companion skills: cometchat-core is the authoritative source for correct init, login, and provider patterns; cometchat-customization explains why drift after customization is expected; cometchat-theming covers the CSS variable cascade for theme-not-applying symptoms.

Purpose

This skill teaches Claude how to diagnose CometChat integration problems systematically. It explains what each diagnostic tool checks, what the known failure modes are and why they happen, and how to distinguish infrastructure problems (env vars, dashboard config, network) from code problems (wrong init sequence, missing CSS import, drift).

1. Use this skill when

The user has a problem with their CometChat integration. Trigger phrases:

• /cometchat troubleshoot
• /cometchat fix
• /cometchat fix <symptom>
• "chat isn't loading"
• "i'm getting a cometchat error"
• "the chat is broken"
• "blank screen on /chat"
• "401 Unauthorized from cometchat"
• "css-variables not loading"
• "the chat doesn't show messages"

2. Docs MCP contract

The CometChat docs MCP at cometchat-docs is a hard requirement for this skill. cometchat doctor handles the local diagnostic checks (integration state, drift, env vars, AST verify rules), but for any symptom that doesn't match a doctor known-issue code, the MCP is the canonical source for symptom → cause → fix.

Hard rules:

1. Always run cometchat doctor first — its known-issues table covers the common failure modes (env-placeholder, env-missing, drift, init-before-login, no-auth-key-in-source).
2. For symptoms NOT in doctor's table, query the docs MCP with the exact error message or symptom keywords. Never guess at the cause.
3. If the docs MCP is not installed, STOP. Tell the user: "Doctor didn't recognize this symptom and I need the CometChat docs MCP to diagnose further. Install it with claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp and re-run."
4. Never blame the user's code if doctor + MCP both pass — the issue is probably infrastructure (network, dashboard config, auth provider).
5. Canonical reference URL: https://www.cometchat.com/docs/ui-kit/react/troubleshooting

3. What cometchat doctor actually checks

Understanding what doctor checks helps you interpret its output and know when to look beyond it:

1. Detection — reads .cometchat/state.json to confirm an integration exists. If absent, reports integrated: false.

2. Env var checks — reads the framework's env file (.env for Vite/Astro/React Router, .env.local for Next.js). Checks each COMETCHAT_* variable for:

   • Presence (key exists in the file)
   • Placeholder sentinels (YOUR_*_HERE still present = warning)

3. AST verify — parses owned TypeScript files and runs 5 checks:

   • css_variables_imported_once — counts @cometchat/chat-uikit-react/css-variables.css imports (must be exactly 1)
   • init_before_login — confirms login() call sites appear after init() resolves (in a .then() chain or after await)
   • render_gated_on_login_resolve — checks that createRoot().render() or JSX is not called at module top level before init completes
   • no_auth_key_in_source — searches string literals for patterns matching auth key format (should be in .env, not source)
   • error_ui_visible_on_failure — confirms that catch handlers set state variables that render visible error UI

4. Drift detection — checksums each file in state.files_owned against the originally applied template. Reports modified or missing files.

When to go beyond doctor: doctor passes but the app still shows a blank screen → likely SSR, network, or dashboard config. Doctor only checks local code and env files.

4. Steps

Step 1 — Triage: read the project state

npx @cometchat/skills-cli info --json

Three possible outcomes:

If drift is detected, surface the modified file list verbatim. Do not automatically offer to restore — drift after using cometchat-customization is expected and correct. Ask the user whether the changes were intentional before suggesting any restore.

Step 1a — Partial-state recovery (aborted /cometchat runs)

info returning integrated: false doesn't always mean the project is clean. /cometchat may have been started, errored out, or been interrupted mid-flow, leaving the project in an inconsistent half-state. Check these markers in parallel before offering to re-run from scratch:

# All four of these can exist independently after a partial run
test -f .cometchat/config.json && cat .cometchat/config.json
grep -l "COMETCHAT_APP_ID" .env .env.local 2>/dev/null
find src app -name "CometChatProvider.*" -o -name "ChatDrawer.*" 2>/dev/null
grep -rln "@cometchat/chat-uikit-react" src app 2>/dev/null | head -5

Interpret the combination:

Rule: always show the user which markers you found before proposing a recovery path. Never delete config.json, env entries, or source files without explicit approval.

Step 2 — Run verify

npx @cometchat/skills-cli verify --json

This runs the AST checks. The output looks like:

{
  "status": "fail",
  "checks": {
    "css_variables_imported_once": { "status": "fail", "reason": "..." },
    "init_before_login": { "status": "pass" },
    ...
  }
}

For each failed check, look up the fix in the table below or via the docs MCP.

Step 3 — Match symptom to known issues

Common doctor issue codes + verify failures and their fixes:

For symptoms not in this table, proceed to Step 4.

Step 4 — Framework-specific patterns

Many issues are framework-specific. Check against these common patterns:

Step 5 — Symptom-driven lookup via the docs MCP

If the user has reported a specific symptom that isn't covered by verify checks or the framework table, query the CometChat docs MCP:

Use the cometchat-docs MCP to search for "<symptom keywords>"

Common symptom searches:

The docs MCP returns the canonical fix. Apply it as a targeted patch.

Step 6 — Propose the fix

Show the user:

1. What's broken (verify output, drift report, or symptom)
2. The likely cause (from the table or docs MCP)
3. The exact fix (file path + content change)
4. Whether to:
   • Patch the specific issue — targeted edit to the broken file. Preferred for most issues.
   • Restore from the registry — cometchat apply --force rewrites all owned files back to their template state. Safe only if the user hasn't customized them. Ask first.
   • Re-run the integration cleanly — cometchat uninstall --force followed by /cometchat. Wipes state.json and starts over. Last resort.

For dashboard/network/auth issues, the fix is on the user's side (CometChat dashboard, .env values, network connectivity) — cometchat doctor surfaces the issue and the fix verbatim. Don't try to "fix" infrastructure issues from the CLI.

Step 7 — Verify the fix

After any fix is applied, re-run:

npx @cometchat/skills-cli verify --json

Confirm status: "pass". If anything is still failing, repeat from Step 2.

Hard rules

• Never apply a fix without showing the user what will change first.
• Never invent error causes — query the docs MCP if you don't know.
• Never blame the user's code if the verify checks are passing — the issue is probably in the docs MCP territory (network, auth, dashboard config).
• For drift, default to showing the drift and asking if it was intentional, not auto-restoring. Drift after customization is expected.
• Always use npx @cometchat/skills-cli.