Troubleshooting

Fixes for install failures, inactive services, empty charts, token errors, and servers that were removed in CloudStats.

Updated Nov 7, 2026

On this page

Installer stops immediately
Enrollment failed
Service is not active
Website shows the server offline
Charts are empty or lag
Duplicate or missing servers after reinstall
Agent will not leave after you deleted the server
Auto-update did not run
What to collect for support

Installer stops immediately#

Message	What to do
`CloudStats Agent supports Linux only.`	Use a Linux host. Windows and macOS are not supported.
`Please run as root: curl -fsSL https://install.cloudstats.me/<token> \	sudo bash`
`Unsupported architecture: …`	The host is not `x86_64` / `amd64` or `aarch64` / `arm64`.
Missing `curl`, `sha256sum`, `bash`, or `systemctl`	Install those tools. The installer does not target a named distro.
`SHA256SUMS does not list …` or checksum failure	Download failed or was truncated. Check HTTPS connectivity and retry.

See Supported platforms.

Enrollment failed#

Message	What to do
`enrollment token is invalid, expired, or revoked`	Copy a new command from Add server. Do not invent a token.
`enrollment token was already used`	Create a new command. Tokens are single-use.
`CloudStats API is not ready; retry shortly`	Wait and retry the same kind of UI command later.
`CloudStats enrollment failed; existing config left unchanged.`	The host kept any previous `agent.json`. Fix the token or API error, then run a new UI command.

These articles do not ask you to send the token.

Service is not active#

systemctl status cloudstats-agent
journalctl -u cloudstats-agent

On a successful current install, systemctl is-active --quiet cloudstats-agent.service is true.

If logs show server-deleted tombstone present; exiting, the host already committed a deleted-server state and exits 87. See Uninstall the agent. To monitor the machine again, add a new server in the UI and install with a new command (Reinstall and server identity).

Website shows the server offline#

The website marks a server online when the agent has contacted CloudStats within 60 seconds. Check that cloudstats-agent is active, the host can reach https://api.cloudstats.me, and the clock is reasonable.

v0.1.0 hosts whose credential was revoked by deleting the server keep retrying 401s and do not uninstall. Remove the agent manually or reinstall v0.2.2.

Charts are empty or lag#

Wait at least two collect intervals (~20 seconds at the default 10s interval). CPU percents and byte/second rates are omitted on the first sample.
Disk and network rates appear per device/interface only after a second sample, and not on counter reset.
Filesystem series are per mountpoint. Some virtual filesystems are skipped; tmpfs is not skipped.
Latest charts show the last accepted batch. A local queue under /var/lib/cloudstats/wal/ drains oldest-first, so the latest snapshot can lag collected_at after an outage.
The website may not chart every name in the catalog even when the agent sends it. Not every catalog name has a dedicated website widget.

Duplicate or missing servers after reinstall#

Same machine id, live server, new token → same server (no duplicate).
Deleted server, then new token → new server id.
Same token twice → second enroll fails; no second server.
Cloned VMs sharing /etc/machine-id → can collapse onto one server.

Details: Reinstall and server identity.

Agent will not leave after you deleted the server#

v0.2.2: wait for the repeated server_deleted window (5 accepted signals over 15 minutes) or run the manual uninstall.
v0.1.0: it will not self-uninstall.

Warning: The following command removes the CloudStats agent, its systemd units, configuration under /etc/cloudstats, and local buffered metrics under /var/lib/cloudstats. It does not delete the server or its metric history in your CloudStats account.

curl -fsSL https://install.cloudstats.me/uninstall.sh | sudo sh

Auto-update did not run#

v0.1.0 never self-updates. Re-run the current installer.
v0.2.0 / v0.2.1 need one installer re-run so the unit has a release URL.
If /etc/cloudstats/no-self-update exists, self-update is skipped.

See Agent updates.

What to collect for support#

Safe:

/usr/local/bin/cloudstats-agent version
systemctl status cloudstats-agent
journalctl -u cloudstats-agent
uname -s -m

Do not send enrollment tokens, /etc/cloudstats/agent.json, or credentials.