Skip to content

Troubleshooting

Common problems and their fixes. Start by checking the logs — docker compose logs -f app — which are phone-free but show connection state, and the health endpoint (curl -sf https://your-domain/healthz → relay-ok).

A number won't connect / is stuck on "initializing"

  1. Open Numbers and click Reconnect on the number.
  2. If it stays stuck, check the logs for that number and confirm the host has enough free RAM (each number needs ~400–800 MB) and that shm_size: "512mb" is set for the app service in docker-compose.yml (too little shared memory crashes Chromium).
  3. As a last resort, remove and re-add the number (re-scan its QR).

The QR code won't scan or keeps expiring

  • QR codes are short-lived — scan promptly after it appears; if it expired, reload the Numbers page to get a fresh one.
  • Scan from the phone that owns the number: WhatsApp → Settings → Linked devices → Link a device.
  • If scanning succeeds but it drops immediately, the phone may have hit WhatsApp's linked- device limit — remove an old linked device and retry.

A number shows offline after a restart

  • Give it 30–60 s — pairings reconnect automatically from the wa_auth volume.
  • If it stays offline, click Reconnect; if that fails, re-scan the QR. A pairing can be torn if it was mid-write during a hot backup.

"This number is offline" when an agent tries to reply

The customer's number is disconnected. Replies deliberately leave from the number the customer wrote to (never another number), so reconnect that number under Numbers and the reply will send.

High memory use / Chromium crashes / the app restarts itself

  • Budget ~400–800 MB per connected number plus the Node process. If the host is undersized, connect fewer numbers or add RAM.
  • Ensure shm_size: "512mb" on the app service. Chromium crashes with too little /dev/shm.

An agent can't see Reports, Templates, or another feature

Those are per-agent permissions. As the workspace manager, open Team, edit the agent, and grant the capability (e.g. View reports, Manage templates). New agents start with only reply/accept/resolve.

Inbound media shows a placeholder instead of the image/file

  • Files over 16 MB are not downloaded (placeholder by design).
  • Media older than 60 days has been pruned to save disk (placeholder remains).
  • File types that aren't inline-safe are offered as a download rather than shown inline.

The inbox isn't updating live

Live updates use Server-Sent Events with an 8-second polling fallback, so the open thread still refreshes even if SSE is interrupted. If nothing updates at all, confirm nginx isn't buffering /inbox/events (the shipped nginx.conf disables buffering for it) and that the browser tab is still connected (reload to re-establish).

Everyone is logged out after a restart / login loops

This means the session-signing secret changed. data/session-secret.txt must persist and be restored with the rest of data/. Confirm it exists and wasn't regenerated; restore it from backup if lost (all existing sessions will need to log in again).

Locked out of the admin panel (lost password or TOTP)

Admin credentials are stored in data/auth.json. To re-run first-time setup:

docker compose exec app sh -c 'mv data/auth.json data/auth.json.bak'
docker compose restart app

Then browse to /admin — you'll be prompted to create a new admin password and scan a fresh TOTP QR. (Workspace-manager and agent logins are unaffected; they live in users.json.) Keep the .bak until you've confirmed the new login works.

Getting more detail

docker compose logs --since 1h app shows the last hour. Connection events, requeue actions, and media/LID timeouts are all logged (never with a phone number). Include the relevant lines when asking for support.