Chatwoot Troubleshooting
Diagnose and fix the common failure modes for the Chatwoot API, CLI, and webhooks.
Quick diagnostics
# 1. Is the base URL reachable?
curl -sI "${CHATWOOT_BASE_URL}" | head -1
# 2. Is the token valid and which identity is it?
curl -s -H "api-access-token: ${CHATWOOT_API_KEY}" \
"${CHATWOOT_BASE_URL}/api/v1/profile" | jq '{id, name, role}'
# 3. Does the account scope resolve?
curl -s -o /dev/null -w "%{http_code}\n" -H "api-access-token: ${CHATWOOT_API_KEY}" \
"${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations"
Authentication & authorization
| Symptom | Cause | Fix |
|---|---|---|
401 Unauthorized |
Missing/typo'd api-access-token header |
Send -H "api-access-token: ${CHATWOOT_API_KEY}" |
401 with a valid token, only behind a reverse proxy |
Proxy drops request headers with underscores (nginx default underscores_in_headers off; Caddy 2.6.4+) so api_access_token never arrives |
Send the hyphenated api-access-token (same header for Chatwoot). The CLI needs v0.7.0+. See "Header check behind a proxy" below |
401 with Authorization: Bearer <token> |
Bearer is accepted only by Chatwoot v4.19.0+ (v4.18.0 is the latest release as of 2026-10-03) | Use api-access-token until the instance runs v4.19.0 or later |
401 with a valid token |
Right token, wrong API family | User token works on /api/v1/..., not /platform/.... Use the platform app token for Platform endpoints |
403 Forbidden |
Token role too low | The action needs admin/agent permission the token lacks — use a token with the right role |
Platform calls all 401 |
Platform API not enabled / wrong token | Platform token comes from the installation Super Admin, not Profile Settings |
Header check behind a proxy
Send the same token with both spellings and compare the status codes. Hyphen 200 plus underscore
401 means the proxy is eating the underscore header, not that the token is bad:
for h in api-access-token api_access_token; do
printf '%s -> ' "$h"
curl -s -o /dev/null -w "%{http_code}\n" -H "$h: ${CHATWOOT_API_KEY}" \
"${CHATWOOT_BASE_URL}/api/v1/profile"
done
Fix: use api-access-token everywhere (scripts, CI, webhooks that call back, CLI >= 0.7.0). If a
legacy client cannot change, set underscores_in_headers on; in the nginx http/server
block (for another proxy, look for its setting on underscore headers).
Wrong scope / not found
| Symptom | Cause | Fix |
|---|---|---|
404 on every account call |
Wrong account_id |
Read it from the dashboard URL .../app/accounts/{id}/... |
404 / HTML instead of JSON |
Wrong base URL or trailing slash | Set CHATWOOT_BASE_URL to the origin only (e.g. https://app.chatwoot.com), no trailing / |
Self-hosted 404/502 |
Reverse proxy or path prefix | Confirm the instance origin and that /api/v1 is exposed |
Request body errors
| Symptom | Cause | Fix |
|---|---|---|
422 Unprocessable |
Missing/invalid fields | Compare the body to the schema: jq '.paths["<path>"].post.requestBody' openapi/application_swagger.json |
| Message sends but is empty/wrong type | Wrong message_type/content_type |
Use message_type: "outgoing" (or "incoming"), private: true for notes |
| Attachment ignored | Sent as JSON | Use multipart/form-data with attachments[] (see pagination-errors.md) |
CLI issues
| Symptom | Cause | Fix |
|---|---|---|
401 on every command behind nginx/Caddy |
CLI older than v0.7.0 sends the underscore header, which the proxy drops | Upgrade the CLI to v0.7.0 or newer |
| Second command on the same conversation fails at once | v0.7.0 per-conversation write lock is held by another process | Wait for the other writer or re-read the conversation; don't retry in a loop |
auth login hangs/fails |
Run in a non-TTY (CI/agent) | Don't script auth login; export CHATWOOT_API_KEY and keep ~/.chatwoot/config.yaml (or pass -a) |
| Agent can't parse output | Default text format | Pass -o json (or -q); never grep text output |
convs returns "too few" |
Defaults to your open queue | Add --assignee all and the right -s status |
| Labels got wiped | label replaces the set |
Fetch existing first and merge; use set -o pipefail (see cli-recipes) |
| Keyring error on login | No system keyring (headless Linux) | Use the CHATWOOT_API_KEY env var instead of the keyring |
| Want to see the HTTP call | Debugging an odd result | Re-run with -v to print request/response |
Webhook problems
| Symptom | Cause | Fix |
|---|---|---|
| Signature never matches | HMAC over parsed JSON | Compute HMAC-SHA256 over the raw body as "{timestamp}.{raw_body}", compare to X-Chatwoot-Signature (sha256=...) |
| No deliveries arrive | URL unreachable / not subscribed | Verify the endpoint is public + returns 2xx; check subscriptions includes the event |
| Bot replies in a loop | Reacting to its own messages | Only act on message_type == "incoming" |
| Duplicate handling | Retried deliveries | De-duplicate on X-Chatwoot-Delivery |
Rate limiting
429 Too Many Requests → add exponential backoff, reduce concurrency, and batch reads with
pagination instead of firing unbounded parallel requests. Limits differ between Cloud and
self-hosted.
When to escalate
- Consistent
5xxon Cloud → check https://status.chatwoot.com; on self-hosted check the Rails/Sidekiq logs. - Suspected token compromise → rotate the access token in Profile Settings immediately.