Agent Issues
Agent connects but never syncs
The agent shows “Waiting: no_sync_needed” repeatedly. Cause: The server hasn’t scheduled a sync yet, or auto-sync is paused. Fix:- Go to Settings and make sure Automatic Sync is On
- Click Sync Now on the Dashboard to trigger a manual sync
- Check your Sync Frequency setting (default: every 4 hours)
“Permission denied” on Mac
macOS blocks the app (“unidentified developer”)
Fix: Remove the quarantine attribute:Windows SmartScreen blocks the app
Fix: Click More info, then Run anyway. This only happens on the first run.”Chrome not found” or browser errors
The agent uses Chrome for automation. If Chrome isn’t installed, it downloads Chromium automatically. If the auto-download fails:- Install Google Chrome manually
- Restart the agent
Agent crashes or exits immediately
Check the terminal output for error messages. Common causes:| Error | Cause | Fix |
|---|---|---|
HOARD_API_URL is required | Missing .env file | Create .env with your config |
HOARD_API_KEY is required | Missing API key | Add your key from Settings |
Failed to load workflow | Wrong path to YAML | Run from the folder containing workflows/ |
launch browser: ... | Chrome/Chromium issue | Install Chrome or check disk space |
Agent is running but dashboard shows “Offline”
The dashboard checksagent_last_seen_at. If the agent is running but shows offline:
- Check the terminal for errors (the agent may be crashing on heartbeat)
- Verify your
HOARD_API_URLis correct (https://www.tryhoard.com) - Check your internet connection
- Verify your API key is valid (check Settings)