Get Relay working

Relay gives Claude and ChatGPT your WhatsApp as 37 MCP tools. Most problems are solved by the checks below. For anything else, ask Relay AI: it answers from the docs, free, with no login.

npx relay-whatsapp-mcp doctor    # checks your install and says what to fix

Troubleshooting

Start with npm run doctor. It catches most of the problems below automatically.

Filter problems

Node.js 22.13 or newer is required

Install the current LTS from nodejs.org; check with node --version.

No QR code, or "session rejected"

In the dashboard choose Retry pairing. On your phone, remove stale entries under Linked devices.

AI says "Start the WhatsApp bridge first"

The local MCP adapter talks to the running bridge: run npm start or npm run service.

Claude connector: 401 Unauthorized

The x-api-key header doesn't match PROXY_KEY. Run npm run setup -- --print and paste the key again.

Claude connector: 404 from the doorway

The doorway can't reach a relay on the same Cloudflare account by URL. Keep the [[services]] binding in claude-proxy/wrangler.toml pointing at your relay Worker's name.

Claude connector: 500 Forwarder is not configured

Upload the doorway secrets: cd claude-proxy && npx wrangler secret bulk .secrets.json.

"Your Mac bridge is offline" from the relay

No device has polled for 45 seconds. Check that npm run service is running and online, and that RELAY_* in .env match the relay's secrets.

409 Another Mac agent is already connected

Two devices are using different RELAY_AGENT_IDs. A standby must reuse the primary's ID.

A send timed out and "may have executed"

Intended behaviour: check the chat with get_messages before trying again. Relay never retries writes automatically.

Both devices answer for a few seconds

Harmless overlap during failover; each request is still handled exactly once.

Auto-start doesn't start (macOS)

launchctl print gui/$(id -u)/com.example.whatsapp-relay.service and data/service.log.

Auto-start doesn't start (Linux)

systemctl --user status whatsapp-relay and journalctl --user -u whatsapp-relay.

Auto-start doesn't start (Windows)

Task Scheduler → WhatsApp Relay → History, and data\service.log.

Port 8787 in use

Set PORT=8789 in .env (and re-run npm run setup -- --print for new configs).

Still stuck?

, read the README and SECURITY.md, or open an issue (for security problems, follow SECURITY.md instead).