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. If you use a dedicated role, confirm it can select from "Message".

Creating a Telegram connection is refused: the message says no Telegram bridge is available. Set NUXT_TELEGRAM_URL and NUXT_TELEGRAM_ADMIN_KEY on the web service, or supply your own bridge.

Telegram is not offered: set both TELEGRAM_API_ID and TELEGRAM_API_HASH on the bridge and restart it. /health reports "telegram": "unconfigured" until both are set.

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 SERVER_PORT=8080 and TELEGRAM_BRIDGE_PORT=8095, then make internal URLs match.

Build cannot find pnpm-workspace.yaml: use the published :1 images, or set the web and bridge root directory to / and 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.

Web fails to start after an upgrade: check for [app-db] errors. Migrations only move forward, so pin images to the major tag and restore Postgres from a backup rather than downgrading. See Releases.

Users or tokens vanished: check that NUXT_DATABASE_URL points at the same Postgres as before. Coming from PocketBase, deploy commit 2e1872e first so the import runs.

Alerts

See Connection alerts for how detection works.

No disconnect email arrives: configure NUXT_SMTP_* and NUXT_MAIL_FROM on the web service, use a sender address your provider accepts, and check for [mailer] errors. Alerts are recorded only after successful delivery.

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

Alerts arrive 10 to 15 minutes after a drop: expected. Every outage serves a 10-minute grace period so short blips that recover on their own mail nobody, and the sweep runs every five minutes.

Sign-in and sign-up

"Sign-up is closed" on a new install: someone already created the first account, or NUXT_SIGNUP_CODE is set and must be entered. Ask an administrator for an invitation. See Who can sign up.

No verification email: check the NUXT_SMTP_* settings and [mailer] logs. With NUXT_EMAIL_VERIFICATION=required and no SMTP host, signups are refused with 503.

Verification email has a code but no link: set NUXT_PUBLIC_APP_URL. The link is never built from the request host.

Passkeys are missing or the browser refuses them: NUXT_PUBLIC_APP_URL must be the exact HTTPS address people open. See Two-factor authentication.