← Dashboard · Docs ·Troubleshooting

Troubleshooting

Connection Issues

Peer shows red dot (offline)

1. Check if peer is running: SSH to peer, check curl http://localhost:5678/api/version

2. Check network: Can you ping the peer's IP?

3. Check route: Try all routes — Tailscale IP, Yggdrasil IP, LAN IP

4. Check firewall: Port 5678 must be open

5. Use relay: If direct connection fails, set peer to relay-preferred

"0 peers connected" but peers are configured

Check ~/.grove/config.json → peers array has entries
Check peer_secret matches between cells
Run opp sync manually: visit dashboard, it triggers on load

Relay won't connect

Check relay URL in config: relay_url: "ws://host:5680" or "wss://domain/relay"
Check relay is running: curl http://relay-host:5680 should respond
Check pubkey is in relay's peer list
For WSS: check nginx config has /relay location block

File Issues

File shows "Under-replicated"

Normal after upload — chunks sync in background (wait 5 min for opp sync)
All peers offline — no targets available; will heal when peers come back
Manual fix: Click "Sync All" or sync individual file

"Grove Only" file won't restore

Need at least one online peer that holds the chunks
Check replication status: which peers have the chunks?
If no peers have it, file may be lost (restore from backup)

Upload stuck / progress bar frozen

Check disk space: df -h
Check Grove logs: tail -f /tmp/grove-web.log
Large files chunk in background — check Activity tab for progress
Refresh page and try again

File not showing in Feed after sharing

Peer must be online to receive the grant
Check: did the share succeed? (toast notification should confirm)
Peer may need to refresh their dashboard
Grant push happens immediately; chunk sync is background

Dashboard Issues

Can't log in

Wrong password: Use the password you set during setup
Locked out: Wait 5 minutes (brute-force lockout) or restart Grove
Reset password: python3 -c "from grove import *; set_dashboard_password('newpassword')"
No password set: First visit goes to /setup to create one

Dashboard blank / won't load

Check if Grove is running: curl http://localhost:5678/api/version
Check logs: tail -20 /tmp/grove-web.log
Check port conflict: lsof -i :5678
Watchdog page at :5679 may have more info

"💀 Grove server lost" message

Dashboard lost contact with backend (3 missed heartbeats)
Grove process may have crashed → check watchdog page
If using systemd: systemctl status grove and journalctl -u grove -n 50
Restart: systemctl restart grove or kill and restart manually

Toasts not showing / real-time updates broken

SocketIO may be blocked by proxy/firewall
Check browser console for WebSocket errors
nginx needs /socket.io proxy block with WebSocket upgrade headers

Performance Issues

Slow sync

Check route speeds: GET /api/route-speeds
Yggdrasil is typically 5-6x slower than Tailscale
Set slow peers to relay-preferred if relay is faster
Reduce replication factor to sync fewer copies
Run benchmark: POST /api/benchmark

High memory usage

systemd limits to 512MB (MemoryMax)
Large file uploads chunk in memory briefly
Many concurrent peers = more connections
Restart to reclaim: systemctl restart grove

Dashboard slow to load

Many files in a directory = slow rendering
Gallery view loads all thumbnails (use list view for 100+ files)
Clear browser cache if JS seems stale after update

Sync Issues

Auto-update keeps recommending same build

Fixed in build 7b70cd7fe25c+: build_time is now deterministic
If still happening: all cells must be on same build
Check builds: curl /api/version on each cell

Chunks exist but file shows "incomplete"

Placement DB may be stale
Trigger sync: click file → Sync
Or rebuild placement: delete ~/.grove/placement.db and restart

"At risk" chunks warning

Some chunks only exist on one peer
That peer going offline = potential data loss
Fix: increase replication factor or add more peers
Opp sync will heal automatically if peers are available

Common Error Messages

Error	Meaning	Fix
`Invalid or missing X-Grove-Secret`	Peer auth failed	Check peer_secret matches
`403 Forbidden`	Not authorized	Log in or provide correct secret
`429 Too Many Attempts`	Login lockout	Wait 5 minutes
`ECONNREFUSED`	Cell not running	Start Grove on that cell
`SSL certificate verify failed`	Bad/expired cert	Renew with `certbot renew`
`MemoryError`	Out of RAM	Restart, reduce concurrent ops
`No space left on device`	Disk full	Free space or reduce storage cap

Getting Help

1. Check this doc first

2. Check logs: /tmp/grove-web.log or journalctl -u grove

3. Check dashboard Activity tab for error entries

4. Ask GroveAI (🤖 tab) — it knows these docs

5. File an issue or ask in chat