sipeed/picoclaw · critical

connect: %w

Error message

connect: %w

What it means

Returned by WhatsAppNativeChannel.Start when client.Connect() fails right after successfully acquiring the QR channel for an unpaired device. whatsmeow's Connect opens its websocket to WhatsApp servers; failure means the socket could not be established at all (DNS, TLS, firewall, proxy) - QR events would never arrive otherwise. The deferred cleanup runs, closing everything.

Source

Thrown at pkg/channels/whatsapp_native/whatsapp_native.go:165

		if startOK {
			return
		}
		c.runCancel()
		client.Disconnect()
		c.mu.Lock()
		c.client = nil
		c.container = nil
		c.mu.Unlock()
		_ = container.Close()
	}()

	if client.Store.ID == nil {
		qrChan, err := client.GetQRChannel(c.runCtx)
		if err != nil {
			return fmt.Errorf("get QR channel: %w", err)
		}
		if err := client.Connect(); err != nil {
			return fmt.Errorf("connect: %w", err)
		}
		// Handle QR events in a background goroutine so Start() returns
		// promptly.  The goroutine is tracked via c.wg and respects
		// c.runCtx for cancellation.
		// Guard wg.Add with reconnectMu + stopping check (same protocol
		// as eventHandler) so a concurrent Stop() cannot enter wg.Wait()
		// while we call wg.Add(1).
		c.reconnectMu.Lock()
		if c.stopping.Load() {
			c.reconnectMu.Unlock()
			return fmt.Errorf("channel stopped during QR setup")
		}
		c.wg.Add(1)
		c.reconnectMu.Unlock()
		go func() {
			defer c.wg.Done()
			for {
				select {

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Verify the host can reach wss://web.whatsapp.com (curl/openssl probe) and that DNS resolves.
2. If a proxy is required, configure HTTPS_PROXY/WSS proxy support for the process.
3. Update picoclaw to a build with a current whatsmeow version when WhatsApp protocol changes break connects.
4. Retry Start after transient network outages; this is a startup-time hard failure.

if _, err := net.LookupHost("web.whatsapp.com"); err != nil {
    return fmt.Errorf("cannot resolve WhatsApp endpoints: %w", err)
}

if err := ch.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "connect:") {
        // network-level failure; check egress/proxy, then retry Start with backoff
    }
}

When it happens

Trigger: Unpaired device + GetQRChannel ok, then whatsapp web websocket (wss to web.whatsapp.com) dial fails: no internet egress, WhatsApp endpoints blocked by firewall/GFW, corporate proxy required but unset, or outdated whatsmeow failing the websocket handshake after a WA protocol change.

Common situations: Hosts in regions where WhatsApp is blocked without a VPN/proxy; datacenter egress filtering; whatsmeow library too old for current WhatsApp server behavior (fixed by library updates); DNS resolution failures for *.whatsapp.com.

Related errors

• get QR channel: %w
• irc connect failed: %w
• create session store dir: %w
• get device store: %w
• whatsapp connection not established: %w

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/98ef3d710a58b75b. Report an issue: GitHub.