Skip to main content
When something goes wrong in Whatsy, the right place to start is always the agent log — it captures everything the background agent does, from connecting to WhatsApp to generating replies. Most problems fall into one of a handful of categories, and every one of them has a straightforward fix. Work through the accordion below that matches your symptom, then follow the steps to get back on track.

​
Common problems

The agent depends on two things being present before it can run: Ollama and Google Chrome. If either is missing or unreachable, the app will hang on the loading screen.Check that Ollama is running:Open Terminal and run:
curl http://localhost:11434/api/tags
If you get a JSON response listing your installed models, Ollama is up. If the request times out or is refused, start Ollama with ollama serve or open the Ollama app from your Applications folder.Check that Google Chrome is installed:Whatsy uses Chrome to drive the WhatsApp web session. If Chrome is not installed at its default location, the agent cannot start. Download Chrome from google.com/chrome and restart Whatsy.Check the agent log:The log captures the exact error that caused the hang:
tail -f ~/Library/Application\ Support/Whatsy/agent.log
Look for lines beginning with [error] or ERR — these will tell you exactly what failed.For deeper help with Ollama, see the Ollama Setup guide.
If the QR code pane stays blank or shows a spinner that never resolves, the agent is not reaching the point where it can render a code.Steps to try:
  1. Close the app completely and reopen it. The agent restarts automatically when the app launches.
  2. Confirm that Google Chrome is installed. Open Finder → Applications and verify Chrome is there. If not, install it from google.com/chrome.
  3. Open the agent log and look for Chrome-related errors:
tail -f ~/Library/Application\ Support/Whatsy/agent.log
Common Chrome errors include Could not find Chrome, spawn ENOENT, or Failed to launch the browser. If you see any of these, reinstalling Chrome and restarting Whatsy should resolve them.For further WhatsApp connection troubleshooting, see the WhatsApp Connection guide.
Whatsy will only send auto-replies when three conditions are met at the same time: auto-reply is enabled, a persona is active, and Ollama is reachable with a loaded model.Check each condition in order:
  1. Enable auto-reply. Open Settings in Whatsy and confirm the auto-reply toggle is on.
  2. Confirm a persona is active. Go to Settings → Personas and make sure at least one persona is set as active. Without an active persona, the agent has no instructions to generate a reply from.
  3. Check the activity feed. The dashboard activity feed shows every incoming message and the agent’s decision about whether to reply. If you see errors like Ollama unreachable or model not found, that is your next stop.
  4. Verify Ollama is running and the model is available:
curl http://localhost:11434/api/tags
If llama3.2 does not appear in the response, pull it:
ollama pull llama3.2
Once all three conditions are met, replies will start sending automatically the next time an eligible message arrives.
Reply quality is driven entirely by your persona definition. If replies feel too formal, too casual, or like they could have come from anyone, the persona needs more detail.Improve your persona:
  • Open Settings → Personas and edit the active persona.
  • In the Tone field, be specific: instead of “friendly”, write something like “casual and warm, uses lowercase, occasionally adds an emoji at the end”.
  • Add more example pairs. Each example trains the model on a real message-and-reply pattern. Aim for at least 8–10 varied examples that cover different topics and tones.
Switch to a larger model:Larger Ollama models produce noticeably more nuanced and context-aware replies. For example:
ollama pull llama3.1:8b
After pulling the model, go to Settings → AI Model and switch to it. You do not need to restart the agent — the change takes effect on the next reply.
Larger models need more RAM. On a Mac with 8 GB of unified memory, llama3.2 is the best balance. On 16 GB or more, llama3.1:8b produces noticeably better results.
Occasional crashes can happen if the agent process exits unexpectedly, usually due to an uncaught error in the WhatsApp bridge or an out-of-memory condition.Steps to recover:
  1. Force-quit the app: press Command + Option + Escape, select Whatsy, and click Force Quit.
  2. Reopen the app — it will restart the agent automatically.
  3. If the crash repeats, read the agent log to find the cause:
tail -100 ~/Library/Application\ Support/Whatsy/agent.log
  1. Confirm you are running macOS 14 or later. Whatsy requires macOS 14 (Sonoma) and will not run reliably on older versions.
If crashes happen consistently, copy the last 50 lines of the agent log before reporting the issue so the team can diagnose it.
Whatsy’s app bridge communicates over a local HTTP server. It tries ports 38472 through 38476 in order. If all five ports are occupied, the agent exits immediately with an error.What causes this:The most common cause is a previous Whatsy instance that did not exit cleanly and is still holding a port open.How to fix it:
  1. Open Activity Monitor (Applications → Utilities → Activity Monitor).
  2. Search for node in the search bar.
  3. Select any node processes that belong to a Whatsy agent and click Force Quit (the × button).
  4. Reopen Whatsy.
If no node processes appear but the error persists, use Terminal to check which process owns the port:
lsof -i :38472
Note the PID in the output and quit that process, then try again.

​
Reading the agent log

The agent log is the single best diagnostic tool available. It records every event the background agent handles — Chrome startup, QR generation, incoming messages, Ollama calls, and reply decisions. Tail it in real time while you reproduce a problem: 
tail -f ~/Library/Application\ Support/Whatsy/agent.log
You can also open the log directly from within Whatsy: if the app shows an error state during onboarding, click Open agent log in the error panel to jump straight to the file in your default text editor.
The log file lives at ~/Library/Application Support/Whatsy/agent.log. It is plain text and safe to share when reporting a bug — but review it first and redact any message content you do not want to share.

​
Still stuck?