Debugging

This guide covers the most common issues when integrating @cognipeer/chat-ui. Each feature guide also has its own Troubleshooting section.

1) Empty screen or collapsed layout

The chat component fills its parent container. Ensure parent has explicit height.

tsx

<div style={{ height: 600 }}>
  <Chat baseUrl="/api/agents" agentId="assistant" />
</div>

2) Messages do not stream

Check:

backend endpoint supports streaming responses (Content-Type: text/event-stream)
proxy/CDN does not buffer chunked responses (for nginx, proxy_buffering off)
browser devtools network panel shows incremental chunks

3) Unauthorized requests

If backend requires auth, pass authorization (or getHeaders for a token that renews) and verify token freshness. A refusal with the code authentication_error shows the localized "Your session has expired. Sign in again to continue." message.

4) History sidebar not updating

Validate session identifiers and backend persistence endpoints. History depends on stable conversation IDs. In a custom layout call history.refresh() when a turn ends.

5) Tool call cards not appearing

Ensure the backend emits tool call events (stream.tool_call) and that a finished message stores its calls in metadata.toolCallDetails. Tool rows show only the latest step and fold the rest under "N previous steps".

6) Theme values not applied

Confirm:

stylesheet imported once (@cognipeer/chat-ui/styles.css)
no host styles override CSS variables unintentionally
themeColors keys match documented token names
theme / themeColors are read when the chat mounts: remount with a key to change them

7) Approval or question cards do not show, or are read-only

The server must be agent-server 0.3.0+ and report pendingActions on GET /conversations/:id.
"Waiting for approval in another app": enableToolApprovals / enableQuestions is off, the transport cannot answer, or a custom list has no actions.onResolve.
The composer is closed: that is pendingActionComposerMode="block" while a card waits.

See Approvals and Questions.

8) A reload loses the running turn

Reattach needs runtime on GET /conversations/:id and the event log route (GET /conversations/:id/events/stream). Check both in the network panel. See Running Turns and Stop.

9) Uploads fail or lack progress

Check the limits the agent publishes (GET /agents → capabilities.attachments), the file route (POST /files), and that your proxy accepts the body size. Progress needs the client's own XMLHttpRequest path (no custom fetch). See File Uploads.

10) Errors show the wrong language or raw text

A code without a string shows the server's message. Check error.code in onError, and add chat.error.code.<code> to customMessages. See Error codes.

11) An embedded chat shows "This chat can't be shown here" or never signs in

Check allowedOrigins, the origin query parameter, that the page is framed, and that the host answers cp:ready with cp:auth. See Embedding the Chat.

Runtime diagnostics checklist

inspect network payloads and response status codes; failed requests carry status, code and details
log onError (with error.code, error.status, error.serverMessage), onMessageSent, onMessageReceived
for approvals log onActionRequired and onActionResolved
for an embed, log the cp:event messages in the host page
isolate issue with ChatMinimal to reduce surface area

Debugging ​

1) Empty screen or collapsed layout ​

2) Messages do not stream ​

3) Unauthorized requests ​

4) History sidebar not updating ​

5) Tool call cards not appearing ​

6) Theme values not applied ​

7) Approval or question cards do not show, or are read-only ​

8) A reload loses the running turn ​

9) Uploads fail or lack progress ​

10) Errors show the wrong language or raw text ​

11) An embedded chat shows "This chat can't be shown here" or never signs in ​

Runtime diagnostics checklist ​

Related docs ​