37 lines
2.0 KiB
Markdown
37 lines
2.0 KiB
Markdown
---
|
||
summary: "Troubleshooting guide for the web gateway/Baileys stack"
|
||
read_when:
|
||
- Diagnosing web gateway socket or login issues
|
||
---
|
||
# Web Gateway Troubleshooting (Nov 26, 2025)
|
||
|
||
## Symptoms & quick fixes
|
||
- **Stream Errored / Conflict / status 409–515:** WhatsApp closed the socket because another session is active or creds went stale. Run `clawdis logout`, then `clawdis login`, then restart the Gateway.
|
||
- **Logged out:** Console prints “session logged out”; re-link with `clawdis login`.
|
||
- **Repeated retries then exit:** Tune reconnect behavior via config `web.reconnect` and restart the Gateway.
|
||
- **No inbound messages:** Ensure the QR-linked account is online in WhatsApp, and check logs for `web-heartbeat` to confirm auth age/connection.
|
||
- **Fast nuke:** From an allowed WhatsApp sender you can send `/restart` to request a supervised restart (launchd/mac app setups); wait a few seconds for it to come back.
|
||
|
||
## Helpful commands
|
||
- Start the Gateway: `clawdis gateway --verbose`
|
||
- Logout (clear creds): `clawdis logout`
|
||
- Relink (show QR): `clawdis login --verbose`
|
||
- Tail logs (default): `tail -f /tmp/clawdis/clawdis-*.log`
|
||
|
||
## Reading the logs
|
||
- `web-reconnect`: close reasons, retry/backoff, max-attempt exit.
|
||
- `web-heartbeat`: connectionId, messagesHandled, authAgeMs, uptimeMs (every 60s by default).
|
||
- `web-auto-reply`: inbound/outbound message records with correlation IDs.
|
||
|
||
## When to tweak knobs
|
||
- High churn networks: increase `web.reconnect.maxAttempts`.
|
||
- Slow links: raise `web.reconnect.maxMs` to give more headroom before bailing.
|
||
- Chatty monitors: increase `web.heartbeatSeconds` if log volume is high.
|
||
|
||
## If it keeps failing
|
||
1) `clawdis logout` → `clawdis login` (fresh QR link).
|
||
2) Ensure no other device/browser is using the same WA Web session.
|
||
3) Check WhatsApp mobile app is online and not in low-power mode.
|
||
4) If status is 515, let the client restart once after pairing (already handled automatically).
|
||
5) Capture the last `web-reconnect` entry and the status code before escalating.
|