Troubleshooting
Common issues and solutions for Wovly.
Installation Issues
macOS: “App is damaged”
xattr -cr /Applications/Wovly.app
macOS: “Cannot be opened because Apple cannot check”
Right-click the app → Open → Click “Open” in the dialog.
Linux: AppImage won’t run
chmod +x Wovly-x.x.x.AppImage
LLM Issues
- Go to Settings
- Enter your API key for Anthropic, OpenAI, or Google
- Save and retry
Slow responses
- Check your internet connection
- Try a different/faster model
- Reduce conversation history length
”Rate limit exceeded”
Wait a few minutes and retry. Consider upgrading your API tier for higher limits.
Integration Issues
Google: OAuth error
- Ensure OAuth consent screen is configured
- Add your email as a test user
- Check redirect URI:
http://localhost:18923/oauth/callback
Slack: “Missing scope”
- Go to your Slack app settings
- Add all required User Token Scopes
- Reinstall the app to your workspace
- Reconnect in Wovly
iMessage: Can’t read messages
- System Preferences → Security & Privacy → Privacy
- Full Disk Access → Add Wovly
- Restart Wovly
Integration shows “Connected” but doesn’t work
- Click Disconnect
- Wait 5 seconds
- Click Connect again
- Re-authorize all permissions
Task Issues
Task stuck on “Waiting”
The task is waiting for an external reply. Check:
- Was the message actually sent?
- Has the recipient replied?
- Try: “Check for replies to the [task name] task”
Task using wrong messaging channel
Wovly detects the channel from your request. Be explicit:
- “In Slack, message Jeff…”
- “Text Sarah…” (for iMessage)
- “Email John…”
Task not progressing
Check the task log for errors. Common causes:
- Integration disconnected
- Rate limits hit
- Approval needed (check Tasks panel)
Browser Automation Issues
Browser not opening
- Install Chrome or Chromium
- Enable browser automation in Settings
- Restart Wovly
Page not loading
Some sites block automation. Try:
- Using a different approach
- Checking if the site requires login
Can’t click element
- Ask Wovly to scroll first
- The element may be in an iframe (not supported)
- Try a different selector
Login failing
- Check credentials in Credentials page
- Ensure domain matches exactly
- Handle 2FA manually if prompted
Memory Issues
Wovly doesn’t remember
- Memory is session-based by default
- Check if memory files exist in
~/.wovly-assistant/memory/
- Try explicit recall: “Do you remember when we discussed…”
Wrong context used
Be specific in your request. Reference the conversation explicitly.
High CPU usage
- Close other applications
- Check for infinite task loops
- Restart Wovly
High memory usage
- Clear conversation history
- Restart Wovly periodically
- Delete old task files
Data Issues
Reset all settings
rm -rf ~/.wovly-assistant/
This deletes all data including integrations, skills, memory, and tasks.
Export data
Copy the entire ~/.wovly-assistant/ folder to back up.
Corrupt settings file
rm ~/.wovly-assistant/settings.json
Getting Help
Logs
Wovly logs to the console. Open DevTools:
- macOS:
Cmd + Option + I
- Windows/Linux:
Ctrl + Shift + I
GitHub Issues
Report bugs at GitHub Issues.
Include:
- Wovly version
- Operating system
- Steps to reproduce
- Error messages from console
Join the community Discord for real-time help and discussion.
