Check the API request status and safe error message first. Never include bearer tokens, passwords, Reverb secrets or customer message content in shared logs.
| Symptom | Check / action |
|---|---|
| Demo chooser missing | Run development mode; copy the Next example env and enable NEXT_PUBLIC_CHAT_DEMO_LOGIN=true; restart. Production deliberately hides it. |
| Login returns 401 | Email/password was rejected, or the account/service/provider is inactive. Check credentials and ask the administrator to verify access; demo fixtures are local-only. |
| Demo login returns 404 in production | Demo login is disabled by design. Use Account sign-in; do not set production APP_ENV=local. |
| Browser network failure | Ensure API process is running on reachable host/8000. A remote phone's localhost is the phone, not your server. |
| Next page appears but buttons do not react | Check Next logs for blocked dev resources/HMR. Configure server-only CHAT_DEV_ALLOWED_ORIGINS with the page hostname/IP (no scheme/port), then restart. This allowlist differs from API CORS. |
| CORS failure | Add the full frontend origin including scheme/port to CHAT_ALLOWED_ORIGINS, then reload server configuration. |
| 401 after working earlier | Demo credentials expire after eight hours; re-open the local session. Production expiry/refresh belongs to host integration. |
| Conversation 404 | ID absent or outside authorized customer/provider/service scope. Confirm mapping; do not weaken authorization. |
| Admin reply 403 | Select Join as admin first. Joining does not grant cross-service access. |
| 422 send error | Text must be nonblank unless a card or attachment is present, at most 5,000 characters, and include a valid UUID client message ID. |
| 409 send error | Resolved conversations reject replies; authorized seller/admin can reopen through status API. Reusing an idempotency key for different text, card or attachment set also conflicts. |
| Attachment rejected (422) | Only JPEG/PNG/WebP images and PDF files are allowed, within max_kilobytes (8 MB default) and max_per_message (5 default). SVG, HTML, archives and other types are refused by content, not extension. |
| Attachment upload fails with no error text | Check the browser network panel: a presigned PUT may be blocked by missing bucket CORS. Confirm the bucket allows PUT from the page origin, or leave the default proxy path. The SDK automatically retries through the API when the direct PUT fails. |
| Attachment image disappears after a while | Signed URLs expire (60 minutes by default). Reopen the conversation or refresh history to mint fresh URLs; there is no in-place refresh. |
| Attachment upload returns 500 "must use a private storage disk" | service-chat.attachments.disk resolves to a disk with visibility => public (often FILESYSTEM_DISK=public). Point it at a private disk, e.g. SERVICE_CHAT_ATTACHMENT_DISK=s3. |
| Attachment stays staged forever | Staged rows are only claimed by a send. Sending an empty body without a card/attachment is refused; type a message or send the attachment alone through the composer. Abandoned uploads are not purged by the backend — add a bucket lifecycle rule. |
| Attachment-only message shows an empty bubble | The adapter predates the attachment layout change. Current React/Vue/widget builds render the bubble only when body or card content exists, with tiles outside it. |
| 429 | Demo API/login rate limit reached; sign-in shows the numeric Retry-After delay when supplied. Wait for that delay (otherwise one minute) and reduce retries. |
| Platform admin cannot open chat | Choose an active Conversation service in Administration, then Open inbox. Account management scope and chat scope are separate. |
| Management action denied | Service admins manage their own provider and seller/customer accounts only. Platform-level service/admin management requires the server's platform-admin permission. |
| New/changed password rejected | Use at least 12 characters with uppercase, lowercase, a number and a symbol. Leave the edit password blank to preserve it. |
| Account edit requires sign-in again | Account changes revoke its sessions by design. Sign in with the current credentials; editing your own account returns to login automatically. |
| Sign-out fails | Network/server failures retain the UI session for retry. A 401 invalid/expired session clears local state and returns to sign-in. Reload discards the local token but is not a successful server revocation. |
| Message saves but peer does not update | Check Reverb process, BROADCAST_CONNECTION=reverb, public key match, reachable browser host/port and Reverb origin allowlist. Refresh/reopen retrieves durable history. |
| WebSocket auth fails | Inspect /api/broadcasting/auth status; use the same user identity as REST. Verify conventional auth endpoint and service/conversation membership. |
| HTTPS page cannot use websocket | Configure HTTPS/wss transport and reachable secure endpoint; browsers may reject mixed-content ws/http. |
| Inbox does not show a new conversation | Select Refresh; inbox push events are not implemented. |
React ChatPanel renders stacked on desktop: header title and conversation list full-width, thread squeezed away, bubbles unstyled | On 0.1.5-era builds Tailwind never scanned the package: add the legacy @source registration from the React/Next.js guide to the host global CSS, or upgrade to a build with the prebuilt stylesheet. On 0.1.6–0.1.8 builds confirm the root layout imports @alzaf-it/chat-react/styles.css. On newer builds the entry imports chat.css automatically: confirm the page loads a stylesheet chunk from @alzaf-it/chat-react/dist (the host bundler must process package CSS). |
| Mobile shows the desktop panel layout (sidebar squeezed beside the thread) | The host page is missing the viewport meta: without width=device-width phones render a ~980px layout viewport, so md breakpoints never match the device. Add it (Next.js viewport export) per the React/Next.js guide. |
React ChatPanel ignores host height classes (h-*/min-h-*/max-h-*) | An explicit height prop sets an inline style and always wins over classes — omit it to size with className. Host utilities apply normally; package height utilities are ac:-prefixed (ac:h-*/ac:min-h-*/ac:max-h-*). Builds up to 0.1.5 also apply the 620px default inline, so only min-h-*/max-h-* clamps take effect there; builds including decision 0006 default to an overridable ac:h-150 class instead. |
| Package styles override host designs on identical Tailwind classes | Builds before decision 0011 emitted unprefixed utilities that fought host utilities (first unlayered-beats-layered, then layer-ordering broke responsive pairs like flex-col/md:flex-row). Upgrade to a build containing decision 0011: every package utility carries the ac prefix, so package selectors never collide with host utilities, and dark: is class-based. Confirm the served chat.css chunk contains .ac\:md\:w-75 and no prefers-color-scheme: dark rule. |
Unit tests fail on require("./chat.css") / import "./chat.css" from @alzaf-it/chat-react | Plain-Node runners (vitest/jest without CSS handling, direct node ESM/CJS imports) cannot load stylesheets. Map *.css to an empty module (vitest alias, jest moduleNameMapper, require.extensions['.css'] stub for CJS, or an ESM loader stub returning an empty module for .css as in scripts/verify-npm-consumer.mjs). Next.js/Turbopack/webpack/Vite process the entry import automatically; no host change needed there. |
| Upload/assignment/help button missing | Attachments are implemented since the attachment release; if the composer has no attach control, the build predates it. Assignment/help/escalation controls remain deferred. |
LAN checklist#
The frontend derives API/Reverb hostname from the page in the Next demo. Open the LAN IP URL, not localhost, on a second device. Allow the API, Reverb and UI ports through the development network's firewall. Update both API full-origin and Reverb hostname allowlists. A server-local HTTP request does not prove a second device can reach the services.
Diagnose without destroying data#
Record operation, time, status code, package versions and a safe reproduction with demo identities. Run relevant checks from testing. Avoid migrate:fresh on real data. Changing credentials or deleting history is not a reconnect fix. For persistent gaps, preserve the reproduction and consult operations.