screenpipe/screenpipe · error

whatsapp not connected

Error message

whatsapp not connected

What it means

The WhatsApp gateway keeps a module-level `sock` (Baileys socket) that is only set after a successful QR/login. `/send` refuses with 503 and this error when `sock` is null, i.e. the gateway process is running but WhatsApp has never connected or has been logged out/disconnected.

Source

Thrown at crates/screenpipe-connect/src/whatsapp/gateway.mjs:109

}

// HTTP server — Pi curls this directly
const server = createServer(async (req, res) => {
  res.setHeader("Content-Type", "application/json");
  const url = parseUrl(req);
  const pathname = url.pathname;

  if (req.method === "POST" && pathname === "/send") {
    let body = "";
    for await (const chunk of req) body += chunk;
    try {
      const { to, text } = JSON.parse(body);
      if (!to || !text) {
        res.writeHead(400);
        return res.end(JSON.stringify({ error: "missing 'to' or 'text'" }));
      }
      if (!sock) {
        res.writeHead(503);
        return res.end(JSON.stringify({ error: "whatsapp not connected" }));
      }
      const jid = toJid(to);
      await sock.sendMessage(jid, { text });
      res.writeHead(200);
      return res.end(JSON.stringify({ success: true, to: jid }));
    } catch (err) {
      res.writeHead(500);
      return res.end(JSON.stringify({ error: err.message || String(err) }));
    }
  }

  if (req.method === "GET" && pathname === "/contacts") {
    if (!sock) {
      res.writeHead(503);
      return res.end(JSON.stringify({ error: "whatsapp not connected" }));
    }
    try {

View on GitHub (pinned to 4ebf712990)

Solutions

1. Open the gateway and scan the QR code to (re)link WhatsApp, then retry the send.
2. Check gateway logs for disconnect reasons; if the socket dropped, restart the gateway process to re-authenticate.
3. Verify the linked device still exists in WhatsApp Settings > Linked Devices.
4. In callers, treat HTTP 503 from `/send` as 'not connected' and pause the automation until health check passes.

Example fix

// before: blind send
await post("/send", { to, text });

// after: gate on connection state
const health = await get("/health"); // or check /contacts success
if (!health.connected) throw new Error("gateway offline: scan QR first");
await post("/send", { to, text });

const res = await fetch(base + "/contacts"); // returns 503 when not connected
if (res.status === 503) throw new Error("WhatsApp not connected — scan the QR code first");

async function sendWithWait(payload, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    const res = await post("/send", payload);
    if (res.status !== 503) return res;
    await sleep(5000 * (i + 1)); // wait for QR scan / reconnect
  }
  throw new Error("WhatsApp gateway stayed disconnected; re-scan QR");
}

When it happens

Trigger: POSTing `/send` before scanning the QR code, after the WhatsApp session was logged out from the phone, after the socket dropped and was not re-established, or when the gateway was restarted and lost its session.

Common situations: Automations firing at boot before the QR scan completes; phone linked device removed by the user; long-running gateway whose session expired; firewall/network interruption killing the socket.

Related errors

• ${err.message || String(err)}
• missing 'to' or 'text'
• err.message || String(err)
• provide 'jid' or 'phone' query param
• not found

AI-assisted analysis of screenpipe/screenpipe@4ebf712990 (2026-09-01). Data as JSON: /api/errors/931ea748a10a8e7e. Report an issue: GitHub.