Server agent not reporting? How to get it back in five minutes

Your server shows as down with "the agent hasn't reported", or never showed up at all. How to check the agent's service and logs, fix a refused token, a blocked connection, a failed install or a machine that went to sleep.

· 6 min read · By the Spot Downtime team

The Spot Downtime agent sends a short report from your server every minute. When three minutes pass without one (or whatever you set under Down after no report for), the server is marked down with the agent hasn't reported in 3m. That means one of three things: the machine is off, the agent isn't running, or its reports can't get through. A few commands on the server tell you which.

Is the whole server down?

If you can't SSH in either, the machine itself is the problem: check your provider's console for a stopped instance, a full disk or a kernel panic. Everything below assumes you can log in.

1. Is the agent running?

bash
sudo systemctl status spotdowntime-agent
  • active (running): it's running; the problem is getting reports out. Go to step 2.
  • inactive (dead) or failed: start it with sudo systemctl enable --now spotdowntime-agent, then read the log (step 2) to see why it stopped.
  • Unit spotdowntime-agent.service could not be found: it isn't installed. Copy the install command from the server's page in Spot Downtime and run it.

2. Read its log

bash
journalctl -u spotdowntime-agent -n 50 --no-pager

The agent logs every failed report. Match what you see:

Log lineWhat it means
Spot Downtime refused the tokenThe token doesn't belong to any server: see step 3
dial tcp … i/o timeoutOutgoing HTTPS is blocked or there's no route: see step 4
no such hostThe server can't resolve spotdowntime.com: check /etc/resolv.conf
x509: certificate signed by unknown authorityThe system's CA certificates are missing, or a proxy intercepts TLS: see step 4
can't read system statsThe agent can't read /proc: it's running somewhere unusual, like a locked-down container

3. The token was refused

Each server monitor has its own token, and the agent sends it with every report. It's refused when the server monitor was deleted (adding it again creates a new token) or the token was mistyped. The agent keeps retrying every 10 minutes in case it's fixed, but it can't fix itself.

Copy the install command from the server's page again and run it. It replaces the token in /etc/spotdowntime-agent.env, sends a test report and restarts the service. Keep the token secret: anyone who has it can report for that server.

4. Reports can't get out

The agent only makes outgoing HTTPS requests to spotdowntime.com on port 443; it opens no ports. Test the same path by hand:

bash
curl -sS -o /dev/null -w "%{http_code}\n" https://spotdowntime.com/api/v1/health
  • 200: the network is fine. Run one report by hand to see the agent's own error: sudo -u spotdowntime-agent env $(sudo cat /etc/spotdowntime-agent.env | xargs) spotdowntime-agent --once
  • Timeout: an egress firewall, security group or network ACL blocks outbound 443. Allow it to spotdowntime.com.
  • Works only through a proxy: add HTTPS_PROXY=http://proxy.internal:3128 to /etc/spotdowntime-agent.env and restart the agent; it uses the standard proxy variables.
  • Certificate errors: install the CA bundle (sudo apt install ca-certificates or sudo dnf install ca-certificates). Behind a TLS-inspecting proxy, add the proxy's CA to the system store.

While reports can't get out, the agent keeps up to three hours of samples and sends them once it reconnects, so the charts fill in the gap.

5. Other causes

The same token on two machines

Cloning a server image copies the agent and its token. Both machines then report as one server: the host name flips between them and the charts mix the two. Give the clone its own server monitor and run its install command there.

The machine sleeps

Laptops, desktops and WSL stop the agent when they sleep. WSL shuts its Linux VM down a few seconds after the last terminal closes, so a server monitor on WSL goes down whenever you close the window. Use always-on machines for monitoring, or pause the monitor while you're away.

The monitor is paused

A paused server keeps its last status and doesn't alert. Resume it from the monitor's menu.

When the install itself fails

Install errorFix
run this as rootRun it with sudo
systemd is requiredThe agent runs as a systemd service. Alpine, older init systems and most containers aren't supported yet
unsupported CPU architectureThe agent supports x86_64 and arm64 Linux
the download's checksum doesn't matchA proxy changed the download, or it was cut short: run the command again
the test report didn't go throughSame causes as steps 3 and 4: wrong token, or the server can't reach spotdowntime.com

Docker containers missing?

If the server reports but its Containers table is empty or shows a permission error, the agent can't read Docker. See permission denied on /var/run/docker.sock; usually re-running the install command with --docker fixes it.

Stuck? Open Ask AI in Spot Downtime and ask why your server isn't reporting. It reads when the agent last reported, its version and its errors, and tells you which step applies. New to the agent? Start with monitoring a Linux server's CPU, memory and disk.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading