Server Monitoring Troubleshooting

Most issues with server monitoring come down to one of three things: the agent isn't running, it can't reach the SiteVitals API, or the alert channels aren't configured correctly.

Work through the relevant section below to diagnose your specific issue.

Dashboard shows "No metrics received yet" or server is Offline

1. Check whether the agent timer or cron is running

# Systemd servers

systemctl status sitevitals-agent.timer

systemctl list-timers sitevitals-agent*

# Cron servers

cat /etc/cron.d/sitevitals-agent

crontab -l

The timer should show active (waiting) and a trigger time in the near future. If it shows failed or inactive, see step 3.

2. Run the agent manually and check the response

This sends a real check and shows you exactly what the API returns:

sudo bash -c '

source /etc/sitevitals/agent.conf

curl -v -X POST "$API_URL/api/v1/server-metrics" \

-H "Authorization: Bearer $API_KEY" \

-H "Content-Type: application/json" \

-d "{\"cpu_percent\":10,\"memory_used_percent\":50,\"memory_used_mb\":1024,\"memory_total_mb\":2048,\"swap_used_percent\":0,\"disk_used_percent\":40,\"disk_used_gb\":20,\"disk_total_gb\":50,\"load_1\":0.1,\"load_5\":0.1,\"load_15\":0.1,\"cpu_core_count\":2,\"collected_at\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"processes\":[]}"

'

A successful response looks like:

{"status":"ok"}

3. Reinstall the agent

If the timer or cron job is missing, reinstall using the command from your server's settings page. If you've lost the command, generate a new API key from Server Settings → Agent → Regenerate API Key.

Note: Regenerating the key immediately invalidates the old one. If you still have the original key, use that to reinstall rather than regenerating unnecessarily.

API errors from the manual check

401 Unauthorized

Cause: The API key in /etc/sitevitals/agent.conf doesn't match what SiteVitals has on record.

Fix: Check the key matches by viewing the conf file: sudo cat /etc/sitevitals/agent.conf. If it's wrong, regenerate the key and reinstall.

405 Method Not Allowed

Cause: The API_URL in the conf file has a redirect (e.g. www → non-www). When curl follows the redirect, the POST becomes a GET.

Fix: Edit /etc/sitevitals/agent.conf and change API_URL to the canonical URL without redirects, e.g. https://www.sitevitals.co.uk.

422 Unprocessable Entity

Cause: The payload failed validation — likely a malformed JSON value.

Fix: View the agent logs with journalctl -u sitevitals-agent.service -n 50 for clues. Running the agent with sudo bash -x /usr/local/bin/sitevitals-agent will trace every variable.

Connection refused / no host

Cause: The server cannot reach the SiteVitals API. Either outbound HTTPS is blocked or the API_URL is empty.

Fix: Verify outbound HTTPS is allowed: curl -I https://www.sitevitals.co.uk. If it times out, check your firewall or security group rules.

Metrics are showing but alerts aren't firing

⚠

No alert channels configured

Go to Server Settings → Alert Channels. If the list is empty, add at least one channel. Thresholds are evaluated but alerts can only be sent if channels exist.
⚠

Threshold not being breached

Check the current values on the dashboard against your configured thresholds. The metric must exceed the threshold and stay there for the "alert after" duration.
⚠

"Alert after" delay hasn't elapsed

If your channel has an "alert after" of 30 minutes but the breach only lasted 10 minutes, no alert will fire. The incident needs to remain open past the delay for the channel to trigger.
⚠

Alert already sent for this incident

Each channel fires once per incident per severity level. If you received one alert and the incident is still ongoing, further alerts for that channel won't fire until severity escalates or a new incident opens.

Uninstalling the agent

To remove the agent from your server completely, run the appropriate commands for your scheduler:

# Systemd

sudo systemctl disable --now sitevitals-agent.timer

sudo rm /etc/systemd/system/sitevitals-agent.service

sudo rm /etc/systemd/system/sitevitals-agent.timer

sudo systemctl daemon-reload

sudo rm /usr/local/bin/sitevitals-agent /etc/sitevitals/agent.conf

# Cron

sudo rm /usr/local/bin/sitevitals-agent

sudo rm /etc/sitevitals/agent.conf

sudo rm /etc/cron.d/sitevitals-agent

After uninstalling, delete the server from SiteVitals via Server Settings → Delete Server to remove all stored checks, incidents and alert channels.

Troubleshooting