Skip to main content
Whatsy connects to WhatsApp as a Linked Device — the same mechanism that powers WhatsApp Web — using Google Chrome to maintain the session in the background. Because of this architecture, connection issues usually trace back to one of three sources: Chrome not being found, the QR code not being scanned in time, or WhatsApp disconnecting the linked session after a period of inactivity. This page covers every scenario and tells you exactly how to fix it.
Whatsy connects to WhatsApp as a Linked Device using the same mechanism as WhatsApp Web. Your messages remain end-to-end encrypted exactly as they are on your phone — Whatsy never decrypts or stores message content outside your Mac.

​
QR code not appearing

If the QR code pane shows a spinner that never resolves, or the panel is blank when the app reaches the connection step, Chrome is most likely the problem. Check that Google Chrome is installed at its default location. Whatsy looks for Chrome at /Applications/Google Chrome.app. Open Finder → Applications and confirm it is there. If not, install Chrome from google.com/chrome and restart Whatsy. Try clicking “Start My Agent” again. If this is not your first launch, the agent may have exited for an unrelated reason. Clicking the button starts a fresh agent process. Check the agent log for Chrome path errors: 
tail -f ~/Library/Application\ Support/Whatsy/agent.log
Look for messages like Could not find Chrome, spawn ENOENT, or Failed to launch the browser. These all indicate that the agent could not start Chrome. Installing or reinstalling Chrome and then restarting Whatsy resolves them in the vast majority of cases.

​
QR code expired

WhatsApp QR codes are valid for approximately 60 seconds. If you do not scan the code within that window, it becomes invalid. You do not need to do anything manually — Whatsy automatically generates a new QR code when the current one expires and refreshes the display. Wait a moment for the new code to appear, then scan it promptly with your phone.
Have WhatsApp open on your phone and navigate to Settings → Linked Devices → Link a Device before the QR code appears, so you can scan it the moment it loads without wasting any of the 60-second window.

​
WhatsApp shows “This device can’t be linked”

This error comes from WhatsApp itself and is not caused by Whatsy. Two things can trigger it: Your WhatsApp app is out of date. WhatsApp occasionally updates the linked-device protocol and drops support for older app versions. Open the App Store on your phone, search for WhatsApp, and install any available update. Then try scanning the QR code again. You have already linked the maximum number of devices. WhatsApp allows up to four linked devices per account. If you have reached that limit, open WhatsApp on your phone → Settings → Linked Devices, remove a device you no longer use, and then try linking Whatsy again.

​
Session disconnected unexpectedly

WhatsApp can disconnect a linked device for several reasons: extended inactivity, logging out on your primary phone, or a WhatsApp server-side session expiry. To reconnect without re-scanning the QR: Open Settings → WhatsApp Connection → Reconnect Device in Whatsy. The agent will attempt to restore the existing session without requiring a new QR scan. If reconnect fails:
  1. Go to Settings → WhatsApp Connection and click Disconnect.
  2. Wait a few seconds for the session to clear.
  3. Click Connect (or relaunch the app) to start a new QR flow.
  4. Scan the QR code with your phone as you did during initial setup.

​
Chrome not found

Whatsy requires Google Chrome to drive the WhatsApp web session. If Chrome is missing or has been moved, the agent will fail to start and the QR code will never appear. Install Chrome: Download and install Google Chrome from google.com/chrome. Make sure the installation completes and Chrome appears in /Applications. After installing Chrome, restart the Whatsy agent: Quit Whatsy completely and reopen it. The agent will pick up Chrome automatically — no configuration is needed.

​
Resetting the WhatsApp session

If the above steps do not resolve your connection problem, clearing the stored WhatsApp session is the most reliable recovery. This tells Whatsy to start a completely fresh connection, as if you were linking WhatsApp for the first time. Run the following command in Terminal: 
rm -rf ~/Library/Application\ Support/Whatsy/data/.wwebjs_auth
Then restart Whatsy and scan the QR code when prompted. Your persona definitions, settings, and activity history are stored separately and will not be affected by this command.
Clearing the session logs out the WhatsApp link entirely. After running this command you must re-scan the QR code to reconnect. You will also need to remove the Whatsy entry from Settings → Linked Devices on your phone to keep things tidy.

​
Still having trouble?

Check the agent log for more detail on what the agent was doing when the connection failed: 
tail -50 ~/Library/Application\ Support/Whatsy/agent.log
If you are also seeing issues with Ollama or the agent not starting at all, see the Common Issues guide and the Ollama Setup guide.