Troubleshooting

Start with a status tool, service health endpoint, and pnpm services:logs. Avoid deleting volumes or relinking accounts until the failure mode is clear.

Connection status

WhatsApp says connected but tools fail: call get-connection-status. A stored state can outlive a dead socket; reconnect from the dashboard when live state is closed.

Telegram reports another process: ensure the bridge has one replica and deployment overlap is disabled. A second process waits on the session lock and should take over after the first exits.

Telegram session ended: link by QR again. Synced chats are retained when the session ends from Telegram Devices, but an explicit Automata unlink deletes them.

Message history

WhatsApp reads return a missing setting: configure NUXT_EVOLUTION_DATABASE_URL, or add the database URL to a bring-your-own connection. Confirm the role can select from "Message".

WhatsApp history is incomplete: full history arrives only during a fresh device link. Ensure DATABASE_SAVE_DATA_HISTORIC=true, then use Import full history and rescan. The phone still decides the ultimate history depth.

Telegram older history stops early: check TELEGRAM_BACKFILL_MAX_PER_CHAT, TELEGRAM_BACKFILL_DAYS, and broadcast settings. Slow backfill is intentional.

Chat counts differ: the dashboard counts conversations reported during pairing, while list-chats counts conversations with stored messages. Use hasMore to detect another result page.

Networking and webhooks

Webhook silently times out on Linux: add the narrow ufw rule from the local deployment guide and verify the container-to-host request.

Private PostgreSQL target is refused: set NUXT_ALLOW_PRIVATE_TARGETS=true only for a trusted local or single-tenant environment. Automata internal targets remain blocked.

Bring-your-own server fails validation: provide both URL and administrator key, verify DNS and TLS, and confirm the origin is allowed by the outbound host guard.

Railway and volumes

Private hostname resolves but connection is refused: confirm PORT=8090, SERVER_PORT=8080, and TELEGRAM_BRIDGE_PORT=8095, then make internal URLs match.

Build cannot find pnpm-workspace.yaml: set the web and bridge root directory to /, then set the Dockerfile path separately.

All WhatsApp accounts unpaired after deploy: verify /evolution/instances is attached and persistent. If the volume was deleted, each account must be scanned again.

Users or tokens vanished: verify /pb_data is attached to PocketBase and restore from a trusted backup if available.

Alerts

No disconnect email arrives: configure PB_SMTP_* on PocketBase, use a valid sender address, and check for [mail] and [mailer] errors. Alerts are recorded only after successful delivery.

Duplicate alert emails: keep the web service at one replica because the hourly sweep runs in-process.

Alerts are delayed: confirm per-connection webhooks reach the public web service. The hourly sweep remains a backstop and may take up to an hour.