Common issues and how to fix them.
Cause: Your API key is wrong, expired, or lacks permissions.
Fix:
- Check for typos (especially leading/trailing spaces)
- Regenerate the key from your provider's dashboard
- Make sure the key has the right permissions
- Check if you've hit spending limits
Cause: You're sending too many requests too fast.
Fix:
- Add delays between requests
- Upgrade your API tier
- Implement exponential backoff
Fix:
- Make sure you're scanning with WhatsApp (not your phone camera)
- Open WhatsApp → Settings → Linked Devices → Link a Device
- Try regenerating the QR code
- Check your network connection
Fix:
- Check if gateway is running (
clawdbot status)
- Look for "disconnected" in logs
- Re-link WhatsApp if needed
- Check if your phone has internet
Fix:
- This sometimes happens after phone restarts
- Re-scan the QR code
- Make sure WhatsApp is updated
Possible causes:
- Memory files not being written
- Memory search not configured
- Context window too small
- Compaction losing important details
Fix:
- Check if memory files exist and are being updated
- Configure semantic search (e.g., local embeddings)
- Use a model with larger context window
- Tune compaction settings
Cause: Hallucination, not a memory bug.
Fix:
- Be more explicit when correcting
- Update memory files manually to fix wrong info
- Consider shorter compaction cycles
Possible causes:
- Using a large/expensive model
- Network issues to API provider
- Context window full (lots of memory loaded)
Fix:
- Try a faster model for simple tasks
- Check API provider status page
- Reduce memory/context being loaded
Fix:
- Use prompt caching if available
- Reduce system prompt size
- Implement smarter memory loading
- Use cheaper models for simple tasks
Got a solution to add? Submit a PR or reach out on synthpals.social!