Troubleshooting

Common issues and solutions

Node Won’t Connect

Symptom: Node shows as “offline” in the dashboard.

Check:

  1. Is the hub reachable from the node? curl http://hub:4865/api/v1/health
  2. Is the node agent running? systemctl status valvet-node
  3. Check node logs: journalctl -u valvet-node -n 50
  4. If behind a reverse proxy, ensure WebSocket upgrade headers are forwarded

Common causes:

  • Firewall blocking port 4865
  • Reverse proxy not forwarding WebSocket headers
  • Node config pointing to wrong hub URL

Backup Fails

Symptom: Job shows “failed” status.

Check:

  1. View job details in the dashboard for the error message
  2. Check node logs for restic output
  3. Verify the repository is accessible from the node
  4. Ensure the backup paths exist on the node

Common causes:

  • Repository password incorrect
  • Insufficient permissions on backup paths
  • Disk full on repository destination
  • Network timeout for remote repositories

”Internal Server Error” on Login

Symptom: Login returns 500 error.

Check:

  1. Hub logs: journalctl -u valvet-hub -n 50 or docker logs valvet
  2. Is the database writable? Check file permissions on the data directory
  3. Is the disk full?

Node Agent Won’t Enroll

Symptom: Enrollment fails with “invalid token” or “token expired”.

Check:

  1. Is the enrollment token correct? Tokens are single-use by default
  2. Has the token expired? Check the token’s expiry in Settings → Tokens
  3. Can the node reach the hub? curl http://hub:4865/api/v1/health

SSE Events Not Working

Symptom: Dashboard does not update in real time.

Check:

  1. Open browser developer tools → Network tab, filter by “events”
  2. If behind a reverse proxy, ensure SSE responses are not buffered
  3. For nginx: set proxy_buffering off

High Memory Usage

Symptom: Hub consuming more memory than expected.

The SQLite database uses WAL mode, which can accumulate a write-ahead log. This is normal. The WAL is checkpointed automatically. If the WAL file grows very large, it may indicate long-running read transactions.

Restic Binary Not Found

Symptom: Node fails with “restic not found”.

The node agent auto-downloads restic on first use. If this fails:

  1. Check if the node can reach the hub’s agent download endpoint
  2. Check disk space and permissions in the node’s working directory
  3. Manually download restic and place it in the agent’s path

Previous

API Reference